# Appointments API

> Appointments in the Broker & Agent API: list appointments; book an appointment; move or change an appointment.

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 appointments](#list-appointments): `GET /appointments`
- [Book an appointment](#book-an-appointment): `POST /appointments`
- [Move or change an appointment](#move-or-change-an-appointment): `PATCH /appointments/{id}`

## List appointments

`GET /appointments`

Soonest first, 200 to a page unless `limit` says otherwise. With `day`, the answer names the `date` and `timezone` it used. A `from` or `to` date alone is that whole day on the clock of the person the key belongs to, and a time without a zone is on that clock too.

Scope: `crm.read`

**Parameters**

| Name | In | Type | |
|---|---|---|---|
| `limit` | query | integer | How many to answer with, 1 to 200. Default `200`. |
| `cursor` | query | string or null | The `nextCursor` of the page before; absent for the first page. Cut to 200 characters. |
| `from` | query | date-time or null | Appointments starting at or after this instant. Cut to 64 characters. |
| `to` | query | date-time or null | Appointments starting at or before this instant. Cut to 64 characters. |
| `day` | query | string or null | today, tomorrow, yesterday or YYYY-MM-DD: that calendar day on the person's own clock, in place of from and to. Cut to 20 characters. |

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

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | A page of appointments. | { `date`: date, `timezone`: string, `appointments`: array of [Appointment](https://brokerandagent.com/developers/api/reference/objects#appointment), `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). |  |
| `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). |  |

## Book an appointment

`POST /appointments`

`startAt` and `endAt` without a zone (`2026-10-12T21:00`) are on the clock of the person the key belongs to; a `Z` or an offset is honored.

Scope: `crm.write` · Role: agent or above

**Body**

| Field | Type | |
|---|---|---|
| `title` (required) | string | Cut to 300 characters. |
| `startAt` (required) | string |  |
| `endAt` | date-time | An unknown value is ignored, not refused. |
| `contactId` | string or null | Cut to 64 characters. |
| `kind` | `showing`, `listing-appt`, `open-house`, `closing`, `inspection`, `meeting`, `call`, `other` | An unknown value is ignored, not refused. |
| `location` | string or null | Cut to 300 characters. |
| `notes` | string or null | Cut to 10000 characters. |

```bash
curl -X POST https://workspace.brokerandagent.com/api/public/v1/appointments \
  -H "Authorization: Bearer bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Call Dana back","startAt":"2026-10-02T15:00:00Z"}'
```

**Responses**

| Status | | Returns |
|---|---|---|
| `201` | The appointment. | { `appointment`: [Appointment](https://brokerandagent.com/developers/api/reference/objects#appointment) } |
| `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). |  |

## Move or change an appointment

`PATCH /appointments/{id}`

Any of `title`, `location`, `notes`, `startAt` and `endAt`; an absent field is left alone and `endAt: null` takes the end off. Times read as in `POST /appointments`. Moving the start alone keeps its length; an end before the start is a 422. A repeating appointment moves as a whole. An agent who can see it may change it, and a coordinator one she booked on a deal, as in the app.

Scope: `crm.write` · Role: transaction-coordinator or above

**Parameters**

| Name | In | Type | |
|---|---|---|---|
| `id` (required) | path | string |  |

**Body**

| Field | Type | |
|---|---|---|
| `title` | string or null | Cut to 300 characters. |
| `location` | string or null | Cut to 300 characters. |
| `notes` | string or null | Cut to 10000 characters. |
| `startAt` | string |  |
| `endAt` | string or null |  |

```bash
curl -X PATCH https://workspace.brokerandagent.com/api/public/v1/appointments/ID \
  -H "Authorization: Bearer bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Call Dana back","location":"…"}'
```

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | The appointment as it now stands. | { `appointment`: [Appointment](https://brokerandagent.com/developers/api/reference/objects#appointment) } |
| `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). |  |

---

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