Appointments API

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

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 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.
Shell
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 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.
Shell
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 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
Shell
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 we’ll fix it.