Skip to content
API reference
/
/
Create an appointment

Create an appointment

Request

Creates a new appointment for the practice identified by X-Practice-Id. The appointment location (site_id) is determined by the site of the practitioner specified in practitioner_id. On success, the newly created appointment is returned in the data envelope with a state of Pending.

Supplied IDs must exist within the practice and be usable for booking. An inactive patient or practitioner, a patient blocked from booking, an inactive appointment reason, or an unavailable room results in 422.

Appointments must also fall within the practitioner's working hours; times that conflict with their schedule, breaks, or blocked periods result in 422.

Security
oauth2(Required scopes: appointment:write)
Headers
X-Practice-Idstring, (uuid)required

UUID of the practice in whose context the request is executed. The API uses this to resolve data the caller is permitted to access for that practice.

Bodyapplication/jsonrequired
patient_idstring, (uuid)required

The UUID of the patient associated with the appointment. The patient must be active within the practice and not blocked from booking appointments.

practitioner_idstring, (uuid)required

The UUID of an active practitioner within the practice. The appointment site (site_id) is determined from this practitioner's assigned site.

room_idstring or null, (uuid)

(Optional) The UUID of the room where the appointment will take place. If provided, this should correspond to a room within the specified site.

start_timestring, (date-time)required

The start time of the appointment in ISO 8601 format. The time should be specified in UTC.

duration_minutesinteger, <= 120

(Optional) The duration of the appointment in minutes. If omitted, the practice's minimum appointment duration is used. When provided, must be greater than or equal to the practice's minimum appointment duration and less than or equal to 120 minutes.

reason_idstring, (uuid)required

The UUID of an active appointment reason configured for the practice.

notesstring or null

(Optional) Additional notes or comments about the appointment.

curl -i -X POST \
  https://docs.api.dentally.com/_mock/docs/versions/2026-01-01/nexgen/appointments \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Practice-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '{
    "patient_id": "3854866a-5476-48be-8313-77029ccdd7a7",
    "practitioner_id": "b80a9cad-c954-44ab-bff4-5e88ba953782",
    "room_id": "05451321-18e1-4bfa-aa22-dfd0080cc120",
    "start_time": "2019-08-24T14:15:22Z",
    "duration_minutes": 120,
    "reason_id": "e93b00b6-69c5-47ba-b0e6-cff780f2f878",
    "notes": "string"
  }'

Responses

Successful response containing the newly created appointment resource (data).

Bodyapplication/json
dataobject(appointment)required

Full details for the newly created appointment.

Response

Wrapper returned by get, create, or update appointment.

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "patient": { … },
    "start_time": "2025-06-01T08:00:00Z",
    "finish_time": "2025-06-01T09:00:00Z",
    "duration_minutes": 60,
    "reason": { … },
    "notes": "Patient requested a morning appointment.",
    "practitioner": { … },
    "site_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "state": "Pending",
    "cancelled_at": null,
    "payment_plan_id": null,
    "room_id": null,
    "created_at": "2025-06-01T08:00:00Z",
    "updated_at": "2026-01-18T12:00:00Z"
  }
}