Skip to main content
POST
Create appointments

Authorizations

​
Authorization
string
header
required

API key from Developers → API Keys, sent as Authorization: Bearer .

Headers

​
Idempotency-Key
string

Any unique string (≤255 chars). A retry with the same key within 24 hours replays the original response (Idempotent-Replayed: true) instead of creating a second record.

Maximum string length: 255

Body

application/json
​
patient_id
integer
required

The patient attending (GET /patients) — must be active. Required on create; not accepted on update. 0 marks a group master session.

Required range: x >= 0
​
location_id
integer
required

The location the visit happens at (GET /locations). Required on create.

Required range: x >= 1
​
appointment_type_id
integer
required

The service being booked (GET /appointment_types). Required on create; changing it on PATCH retypes the visit under the same guards as a move — refused once processed, cancelled or missed.

Required range: x >= 1
​
practitioner_id
integer
required

The practitioner the visit is booked with (GET /practitioners). Required on create; can't be null on update — an appointment is moved to someone else, never unassigned.

Required range: x >= 1
​
starts_at
string
required

Visit start, YYYY-MM-DDTHH:MM:SS in the clinic's timezone. Required on create. Changing it resets any pending reminder sends for the visit. The account's wall-clock time, YYYY-MM-DDTHH:MM:SS, no zone suffix.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$
Example:

"2026-09-09T10:30:00"

​
resource_id
integer | null

Required when the location uses a resource-view calendar (locations.calendar_view = 1) — the room/table the appointment sits in, from GET /resources for that location. Leave it out for practitioner-view locations (calendar_view = 2). The room, table or bench the visit sits in, from GET /resources. Required at resource-view locations (calendar_view = 1); leave it out at practitioner-view locations (calendar_view = 2).

Required range: x >= 1
​
ends_at
string | null

Visit end, YYYY-MM-DDTHH:MM:SS clinic time, after start. Omitted on create it's derived from the practitioner's duration for the type, else the type's, else 30 min; on update it keeps the current duration. The account's wall-clock time, YYYY-MM-DDTHH:MM:SS, no zone suffix.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$
Example:

"2026-09-09T10:30:00"

​
note
string | null

Free-text note on the visit, ≤ 1000 chars. Editable in any state, even processed.

Maximum string length: 1000
​
columns
integer | null

How many of the practitioner's calendar columns the visit spans (1 to 100). Omitted on create it takes the appointment type's default; change it to widen or narrow the block on the diary. Omit it (or send null) on an update to leave it as it is.

Required range: 1 <= x <= 100
​
metadata
object

Integrator-owned key/value metadata (max 50 keys). Values are strings (≤500 chars), numbers or booleans and read back with the type they were written with. On write, a null value removes the key. Filter with metadata[key]=op:value; number operands compare numerically.

Response

The resource

​
data
object
Example: