Update an appointment

Request

Updates the appointment matching id for the practice identified by X-Practice-Id. Only the fields provided in the request body will be modified; omitted fields remain unchanged. If no appointment exists for that practice and id, the API responds with 404. When reason_id is provided, it must refer to an active appointment reason; otherwise the API responds with 422. When start_time or duration_minutes is provided, the resulting appointment must fall within the practitioner's working hours and must not conflict with any blocked or unavailable periods; otherwise the API responds with 422.

Security

oauth2(Required scopes: appointment:write)

Path

idstring, (uuid)required

Resource identifier to filter/find.

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

start_timestring, (date-time)

The new 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. 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)

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

curl -i -X PATCH \
  'https://docs.api.dentally.com/_mock/docs/versions/2026-01-01/nexgen/appointments/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Practice-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '{
    "start_time": "2019-08-24T14:15:22Z",
    "duration_minutes": 120,
    "reason_id": "e93b00b6-69c5-47ba-b0e6-cff780f2f878"
  }'

Responses

Successful response containing the updated appointment resource (data).

Bodyapplication/json

dataobject(appointment)required

Full details for the updated 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"
  }
}