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

Base URL: `https://workspace.brokerandagent.com/api/public/v1`. Every call needs an [API key or OAuth token](https://brokerandagent.com/developers/api/authentication).

- [List contacts](#list-contacts): `GET /contacts`
- [Add a contact](#add-a-contact): `POST /contacts`
- [Get a contact](#get-a-contact): `GET /contacts/{id}`
- [Change a contact](#change-a-contact): `PATCH /contacts/{id}`
- [Add a note to a contact's timeline](#add-a-note-to-a-contact-s-timeline): `POST /contacts/{id}/notes`
- [A contact's recent activity](#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 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. |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#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. |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#contact) or null, `matched`: `true` } |
| `201` | Created. | { `contact`: [Contact](https://brokerandagent.com/developers/api/reference/objects#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 |  |

```bash
curl https://workspace.brokerandagent.com/api/public/v1/contacts/ID \
  -H "Authorization: Bearer bak_YOUR_KEY"
```

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | The contact. | { `contact`: [Contact](https://brokerandagent.com/developers/api/reference/objects#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. |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#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. |

```bash
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`. |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#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). |  |

---

Source: https://brokerandagent.com/developers/api/reference/contacts
