Automations API

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

Generated from the product on Nov 17, 2026

Base URL: https://workspace.brokerandagent.com/api/public/v1. Every call needs an API key or OAuth token.

List automations#

GET /flows

Scope: crm.read

Shell
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 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.
Shell
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.
Shell
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 we’ll fix it.