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 timeline; and more.

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 contacts#

GET /contacts

Every contact the credential’s person can see, in id order, a page at a time.

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.
Shell
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: agent or above

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.
Shell
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
Shell
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 replaces it: 422).

Scope: crm.write · Role: agent or above

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.
Shell
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: agent or above

Parameters

Name In Type
id (required) path string

Body

Field Type
body (required) string Cut to 10000 characters.
Shell
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.
Shell
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 we’ll fix it.