Contacts API
Contacts in the Broker & Agent API: list contacts; add a contact; get a contact; change a contact; add a note to a contact's
Base URL: https://workspace.brokerandagent.com/api/public/v1. Every call needs an API key or OAuth token.
- List contacts:
GET /contacts - Add a contact:
POST /contacts - Get a contact:
GET /contacts/{id} - Change a contact:
PATCH /contacts/{id} - Add a note to a contact’s timeline:
POST /contacts/{id}/notes - A contact’s recent activity:
GET /contacts/{id}/timeline
List contacts#
GET /contacts
Every contact the credential’s person can see, in id order, a page
Scope: crm.read
Parameters
| Name | In | Type | |
|---|---|---|---|
limit |
query | integer | How many to answer with, 1 to 100. Default 25. |
cursor |
query | string or null | The nextCursor of the page before; absent for the first page. Cut to 200 characters. |
email |
query | string or null | Exact match, any case. Cut to 300 characters. |
phone |
query | string or null | Digits; matches the end of the number. Cut to 40 characters. |
q |
query | string or null | Name contains, any case. Cut to 200 characters. |
stage |
query | string or null | A pipeline stage id: new, engaged, qualified, touring, under-contract, closed or nurture. Cut to 60 characters. |
curl https://workspace.brokerandagent.com/api/public/v1/contacts \
-H "Authorization: Bearer bak_YOUR_KEY"Responses
| Status | Returns | |
|---|---|---|
200 |
A page of contacts. | { contacts: array of Contact, nextCursor: string or null } |
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). |
Add a contact#
POST /contacts
Created through the same path the app uses. When the email or phone (last ten digits) matches a contact the credential can see, that contact comes back with matched: true instead of a duplicate, so a retry of a contact with an email or phone is safe. A lead-capture credential learns nothing about the book: it always gets 202. So does a match with a company lead the credential’s person can’t see: nothing new is made, and the answer doesn’t say whether anyone matched. A Free workspace holds up to 100,000 contacts plus 25,000 for each extra login; past that, adding a contact answers 402 with the reason in message (a lead-capture credential is never refused, and POST /events always lands).
Scope: leads.write · Role:
Body
| Field | Type | |
|---|---|---|
name (required) |
string | Cut to 200 characters. |
email |
string or null | Cut to 300 characters. |
phone |
string or null | Cut to 40 characters. |
intent |
buy, sell, both, rent, unknown |
An unknown value is ignored, not refused. |
tags |
array of string | Up to 20 items. An unknown value is ignored, not refused. |
areas |
array of string | Up to 20 items. An unknown value is ignored, not refused. |
budgetMin |
number or string | An unknown value is ignored, not refused. |
budgetMax |
number or string | An unknown value is ignored, not refused. |
source |
string or null | Cut to 40 characters. |
curl -X POST https://workspace.brokerandagent.com/api/public/v1/contacts \
-H "Authorization: Bearer bak_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Dana Reyes"}'Responses
| Status | Returns | |
|---|---|---|
200 |
Matched an existing contact the credential can see. | { contact: Contact or null, matched: true } |
201 |
Created. | { contact: Contact, matched: false } |
202 |
Accepted: from a lead-capture credential, or matching a company lead the credential can’t see. | { contact: null, matched: null } |
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). | |
402 |
The workspace’s plan doesn’t include this, or the workspace is at one of its plan’s limits, named in the message (upgrade_required). | |
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). |
|
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). |
Get a contact#
GET /contacts/{id}
Scope: crm.read
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string |
curl https://workspace.brokerandagent.com/api/public/v1/contacts/ID \
-H "Authorization: Bearer bak_YOUR_KEY"Responses
| Status | Returns | |
|---|---|---|
200 |
The contact. | { contact: Contact } |
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). | |
429 |
Too many requests for this credential; wait for Retry-After (rate_limited). |
Change a contact#
PATCH /contacts/{id}
Any subset of the create fields plus custom (merged into the contact’s custom fields; null deletes a key). An absent field is left alone; null clears it. stage moves them as the board does, to that stage’s own column: a move can start the workspace’s stage-change automations, lost stops theirs, and the stage they’re in already changes nothing. addTags and removeTags change the tags without sending the whole list (not together with tags, which
Scope: crm.write · Role:
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string |
Body
| Field | Type | |
|---|---|---|
name |
string or null | Cut to 200 characters. |
email |
string or null | Cut to 300 characters. |
phone |
string or null | Cut to 40 characters. |
intent |
buy, sell, both, rent, unknown |
An unknown value is ignored, not refused. |
tags |
array of string | Up to 20 items. An unknown value is ignored, not refused. |
areas |
array of string | Up to 20 items. An unknown value is ignored, not refused. |
budgetMin |
number or null | An unknown value is ignored, not refused. |
budgetMax |
number or null | An unknown value is ignored, not refused. |
custom |
object | |
stage |
new, engaged, qualified, touring, under-contract, closed, nurture, lost |
|
addTags |
array of string | Up to 20 items. An unknown value is ignored, not refused. |
removeTags |
array of string | Up to 20 items. An unknown value is ignored, not refused. |
curl -X PATCH https://workspace.brokerandagent.com/api/public/v1/contacts/ID \
-H "Authorization: Bearer bak_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Dana Reyes","email":"dana@example.com"}'Responses
| Status | Returns | |
|---|---|---|
200 |
The contact as it now stands. | { contact: Contact or null } |
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). | |
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). |
Add a note to a contact’s timeline#
POST /contacts/{id}/notes
Scope: crm.write · Role:
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string |
Body
| Field | Type | |
|---|---|---|
body (required) |
string | Cut to 10000 characters. |
curl -X POST https://workspace.brokerandagent.com/api/public/v1/contacts/ID/notes \
-H "Authorization: Bearer bak_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"body":"Prefers texts after 5pm"}'Responses
| Status | Returns | |
|---|---|---|
201 |
The note. | { note: 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). |
A contact’s recent activity#
GET /contacts/{id}/timeline
Newest first.
Scope: crm.read
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string | |
limit |
query | integer | How many to answer with, 1 to 200. Default 50. |
curl https://workspace.brokerandagent.com/api/public/v1/contacts/ID/timeline \
-H "Authorization: Bearer bak_YOUR_KEY"Responses
| Status | Returns | |
|---|---|---|
200 |
Timeline events. | { events: array of TimelineEvent } |
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). | |
429 |
Too many requests for this credential; wait for Retry-After (rate_limited). |
Something missing or wrong? Email support@brokerandagent.com and