Skip to main content
POST
Book an appointment

Authorizations

Authorization
string
header
required

Service (M2M) access token issued by POST /auth/token using the client_credentials grant. Required scopes, where known, are listed on each operation below.

Headers

Idempotency-Key
string
required

Required. A UUID your client generates, one per attempt. The first request under a key is processed and its response stored for 24 hours; a later request under the same key returns that stored response with x-idempotency-replayed: true instead of writing again, so a retry after a timeout cannot double-book. Failures are stored too — use a new key whenever you change the request or search for a new slot. Omitting the header is a 400 (missing-idempotency-key). A key is global to your integration, not scoped to an endpoint or an appointment, so mint a fresh UUID per action rather than deriving one from the resource — a key already spent on a booking will replay that booking if you send it on a later cancel or complete.

Required string length: 1 - 255

Body

application/json
slot_token
string

A slot_token from a slot search. Mutually exclusive with reservation_id.

Required string length: 1 - 8192
reservation_id
string<uuid>

A reservation_id from a hold. Mutually exclusive with slot_token.

patient_id
string<uuid>

The patient, as returned by POST /patients. Required only when the slot_token names no patient — that is, when the slot search did not send patient_id. Otherwise optional: a matching value is accepted, and a different one is a 400 (slot_token.patient_mismatch). Omit on the reservation_id path.

notes
string

Pre-visit notes for the appointment, up to 2000 characters. Plain text only: a value containing < or > is rejected with a 400 (appointment.notes-invalid-html).

Maximum string length: 2000

Response

The booked appointment, including the assigned provider.

A booked appointment. Returned bare (not wrapped in a data envelope) by the single-appointment endpoints. Carries no organization_id — your org comes from the access token.

id
string<uuid>
required
provider_id
string<uuid>
required

The provider scheduling assigned at book time.

patient_id
string<uuid>
required
start
string<date-time>
required
end
string<date-time>
required
status
enum<string>
required

Lifecycle state. closed is terminal; read outcome for how it closed.

Available options:
open,
closed
created_at
string<date-time>
required
updated_at
string<date-time>
required
outcome
enum<string>

Present once the appointment closes.

Available options:
completed,
no_show,
cancelled,
unresolved
state
string

Two-letter US state the visit was licensed against.

Required string length: 2
closed_at
string<date-time>

When the appointment closed, however it closed — completed, no-show or cancelled. Present once status is closed.

cancelled_at
string<date-time>
cancel_reason
string
notes
string

Pre-visit notes, when the booking set them.

external_refs
object[]

Identifiers this appointment carries in downstream systems.