Automations API
Automations in the Broker & Agent API: list automations; start an automation for a contact; stop an automation
Base URL: https://workspace.brokerandagent.com/api/public/v1. Every call needs an API key or OAuth token.
- List automations:
GET /flows - Start an automation for a contact:
POST /flows/{id}/enroll - Stop an automation for a contact:
POST /flows/{id}/unenroll
List automations#
GET /flows
Scope: crm.read
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 } |
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
Scope: automations.run · Role:
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string |
Body
| Field | Type | |
|---|---|---|
contactId (required) |
string | Cut to 64 characters. |
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
Scope: automations.run · Role:
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string |
Body
| Field | Type | |
|---|---|---|
contactId (required) |
string | Cut to 64 characters. |
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). |
Something missing or wrong? Email support@brokerandagent.com and