Skip to main content
GET
Retrieve 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.

Path Parameters

id
string<uuid>
required

The appointment id.

Query Parameters

state_history
enum<string>
default:false

Include the status-transition log as a state_history page.

Available options:
true,
false
reschedule_history
enum<string>
default:false

Include the reschedule chain as a reschedule_history page.

Available options:
true,
false
history_limit
default:25

Maximum entries per page, applied to both requested logs. Defaults to 25. There is no declared maximum, so a larger value is accepted rather than rejected, but the page size is capped at 100 — ask for more and you get 100. Values below 1 return 400. Named history_limit rather than limit because one value sizes two nested logs.

Required range: x >= 1
state_history_cursor
string

Opaque after or before value from a previous state_history page, passed back verbatim. Requires state_history=true — sending it alone is a 400 rather than a silent no-op.

Maximum string length: 8192
Pattern: ^[A-Za-z0-9_-]+$
reschedule_history_cursor
string

Opaque after or before value from a previous reschedule_history page, passed back verbatim. Requires reschedule_history=true — sending it alone is a 400 rather than a silent no-op.

Maximum string length: 8192
Pattern: ^[A-Za-z0-9_-]+$

Response

The appointment, plus whichever history sub-objects you asked for.

An appointment as returned by the retrieve endpoint: the appointment, plus either audit log you opted into. Both sub-objects are absent unless the request asked for them. Returned bare — single-resource responses carry no request_id; that field is on the collection envelopes only.

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.

state_history
object

Present only when the request carried state_history=true.

reschedule_history
object

Present only when the request carried reschedule_history=true.