Requests, errors and limits
The conventions every API call follows, including JSON, times and dates, pagination, errors, plan limits and
Format#
- JSON in, JSON out. Send
Content-Type: application/jsonwith a body. - Dates are ISO 8601 strings, like
2026-10-02T15:00:00Z. Date-only fields useYYYY-MM-DD. - Text is trimmed and cut to the field’s length
rather than refused. - An unknown choice, like an intent or a task kind we don’t have, is ignored
rather than refused. - In a
PATCH, a field you leave out is left alone, andnullclears it. - Custom field values arrive as text (numbers and true/false are converted), at most
50 per request.
Times and time zones#
- A time without a zone is read on the clock of the person behind the credential.
2026-10-14T17:00is 5 PMwhere they are. - A date alone, where a time is expected, is 10 AM that day
on their clock. - A
fromortothat’s a date alone coversthat whole day. - Days, like a deal’s contract and closing dates, are sent as that day’s UTC midnight. Read them as a date,
not a moment.
Pagination#
Lists that can grow long page by cursor. Pass limit, then pass the answer’s nextCursor as cursor to get the next page. A null nextCursor means you’ve
curl "https://workspace.brokerandagent.com/api/public/v1/contacts?limit=25&cursor=ct_…" \
-H "Authorization: Bearer bak_YOUR_KEY"- Paged by cursor:
/contacts,/inbox/threads,/documents,/smart-lists/{id}/members,/tasks,/appointmentsand/envelopes. - Paged only when you pass
limit:/transactionsand/tours. Withoutlimittheyanswer with everything. - Page sizes differ. The default is 25 for contacts, 50 for threads and
200 for tasks. - A
limitabove the call’s maximum is treated as that maximum, and one below1 as 1.
A cursor for a record that has since been deleted answers 422; start again from
Errors#
Every error has the same shape:
{ "error": { "code": "validation", "message": "email: Not a valid email address" } }Branch on code, never on the wording of message,
| Status | Code | Meaning |
|---|---|---|
400 |
bad_json |
The body isn’t a JSON object |
400 |
bad_idempotency_key |
The Idempotency-Key is malformed. See Retrying safely |
401 |
unauthorized, workspace_suspended |
See Authentication |
402 |
upgrade_required |
The workspace’s plan doesn’t include this, or the workspace is at a plan limit. The reason is in message |
403 |
insufficient_scope, insufficient_access, forbidden, workspace_not_granted, wrong_audience, ip_not_allowed, ai_apps_off, awaiting_approval |
The credential can’t do this, or can’t reach this record or workspace. See Authentication |
404 |
not_found |
No such record, or none the credential can see |
409 |
idempotency_in_progress |
A request with the same Idempotency-Key is still running. Retry after Retry-After |
409 |
flow_off |
The automation you tried to start is switched off |
409 |
in_progress |
A copy of the same request is still being handled |
422 |
validation |
A field is the wrong kind; the message names it |
422 |
idempotency_key_reused |
The same Idempotency-Key came with a different body or path |
429 |
rate_limited |
Too many requests; see below |
500 |
internal |
Something went wrong on our side |
503 |
unavailable |
Briefly unavailable. Retry shortly |
Rate limits#
Each key or connection can make 120 requests a minute, and each IP address gets 10 tries a minute with a bad credential. Over either, calls answer 429 rate_limited with a Retry-After: 60 header. Wait, then retry. Spreading requests out works
There are no RateLimit-* headers yet, and the count is approximate, since it’s kept
Plan limits#
The API is on every Workspace plan, Free included. A workspace at a plan limit answers 402 upgrade_required, with the reason in message.
Today one call can meet a limit: POST /contacts, when a Free workspace already holds its 100,000 contacts, plus 25,000 for each extra login. Leads always land: lead-capture keys, POST /events and POST /site-leads are never refused
Some answers follow the workspace’s add-ons rather than refusing. Without the collaboration add-on, GET /reports covers the credential’s own person, and calendar attendees are left
Answers that wait for a person#
A connected app (OAuth) can be set to ask its person first. Then starting an automation or removing a tour stop answers 202 with a proposal, and nothing runs until the person approves it in the app. API keys never ask first. See Build an app with OAuth.
Build for change#
Within v1 the API only grows: new calls, new fields, new values. Ignore fields and values you don’t recognize, and your integration keeps working. See Versioning and changes.
Something missing or wrong? Email support@brokerandagent.com and