Appointments API
Appointments in the Broker & Agent API: list appointments; book an appointment; move or
Base URL: https://workspace.brokerandagent.com/api/public/v1. Every call needs an API key or OAuth token.
- List appointments:
GET /appointments - Book an appointment:
POST /appointments - 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
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. |
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, 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
Scope: crm.write · Role:
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. |
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 } |
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
Scope: crm.write · Role:
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 |
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 } |
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). |
Something missing or wrong? Email support@brokerandagent.com and