Skip to main content
PATCH
Update 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

A key you generate, one per update attempt. A retry under the same key replays the stored response instead of applying the change twice. Omitting it 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

Path Parameters

id
string<uuid>
required

The appointment id.

Body

application/json

Exactly one named change per request. The arms are mutually exclusive: sending two is a 400 (conflicting-patch), sending none is a 400 (empty-patch).

cancel
object
required

Cancel the appointment. Send {} to cancel without a reason.

Response

The updated appointment — or, on the reopen arm, the appointment plus the mechanism that restored it.

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.