# Automations API

> Automations in the Broker & Agent API: list automations; start an automation for a contact; stop an automation for a contact.

Base URL: `https://workspace.brokerandagent.com/api/public/v1`. Every call needs an [API key or OAuth token](https://brokerandagent.com/developers/api/authentication).

- [List automations](#list-automations): `GET /flows`
- [Start an automation for a contact](#start-an-automation-for-a-contact): `POST /flows/{id}/enroll`
- [Stop an automation for a contact](#stop-an-automation-for-a-contact): `POST /flows/{id}/unenroll`

## List automations

`GET /flows`

Scope: `crm.read`

```bash
curl https://workspace.brokerandagent.com/api/public/v1/flows \
  -H "Authorization: Bearer bak_YOUR_KEY"
```

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | Every flow with whether it's on and what starts it. | { `flows`: array of [Flow](https://brokerandagent.com/developers/api/reference/objects#flow) } |
| `401` | No credential, or one that's unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). |  |
| `403` | The credential lacks the scope (insufficient_scope, naming it in `scope`), the record isn't the person's to change (forbidden), the connection wasn't granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant's tools (wrong_audience). |  |
| `429` | Too many requests for this credential; wait for Retry-After (rate_limited). |  |

## Start an automation for a contact

`POST /flows/{id}/enroll`

Enrolls a contact once; a repeat answers 200 with `enrolled: false`. Needs the automations.run scope.

Scope: `automations.run` · Role: agent or above

**Parameters**

| Name | In | Type | |
|---|---|---|---|
| `id` (required) | path | string |  |

**Body**

| Field | Type | |
|---|---|---|
| `contactId` (required) | string | Cut to 64 characters. |

```bash
curl -X POST https://workspace.brokerandagent.com/api/public/v1/flows/ID/enroll \
  -H "Authorization: Bearer bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contactId":"ct_…"}'
```

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | Already enrolled. | { `enrolled`: `false` } |
| `201` | Enrolled. | { `enrolled`: `true` } |
| `202` | Held for the person to approve in the app: the connection asks before sending or deleting. Nothing has run yet. | { `proposal`: object } |
| `400` | The body isn't a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key). |  |
| `401` | No credential, or one that's unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). |  |
| `403` | The credential lacks the scope (insufficient_scope, naming it in `scope`), the record isn't the person's to change (forbidden), the connection wasn't granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant's tools (wrong_audience). |  |
| `404` | No such record, or one the credential's person can't see (not_found). |  |
| `409` | A request with this Idempotency-Key is still being handled (idempotency_in_progress, with Retry-After), or the call conflicts with the record's state (flow_off, in_progress). |  |
| `422` | A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused). |  |
| `429` | Too many requests for this credential; wait for Retry-After (rate_limited). |  |

## Stop an automation for a contact

`POST /flows/{id}/unenroll`

Stops that contact's run where it is, as Stop on their page does: the steps left don't run and nothing is sent. It won't run for them again unless someone resumes it there. `stopped: false` when it wasn't running for them, so a repeat is safe. Needs the automations.run scope.

Scope: `automations.run` · Role: agent or above

**Parameters**

| Name | In | Type | |
|---|---|---|---|
| `id` (required) | path | string |  |

**Body**

| Field | Type | |
|---|---|---|
| `contactId` (required) | string | Cut to 64 characters. |

```bash
curl -X POST https://workspace.brokerandagent.com/api/public/v1/flows/ID/unenroll \
  -H "Authorization: Bearer bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contactId":"ct_…"}'
```

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | Stopped, or it wasn't running for them. | { `stopped`: boolean } |
| `400` | The body isn't a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key). |  |
| `401` | No credential, or one that's unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). |  |
| `403` | The credential lacks the scope (insufficient_scope, naming it in `scope`), the record isn't the person's to change (forbidden), the connection wasn't granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant's tools (wrong_audience). |  |
| `404` | No such record, or one the credential's person can't see (not_found). |  |
| `409` | A request with this Idempotency-Key is still being handled (idempotency_in_progress, with Retry-After), or the call conflicts with the record's state (flow_off, in_progress). |  |
| `422` | A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused). |  |
| `429` | Too many requests for this credential; wait for Retry-After (rate_limited). |  |

---

Source: https://brokerandagent.com/developers/api/reference/automations
