Conventions

These are the conventions you can rely on across every operation in the contract. They are enforced by the spec; if you spot a deviation, please report it to the APIs & Partnerships team — it is a bug.

Transport

HTTPS in deployed environments.
JSON for request and response bodies (application/json; charset=utf-8).
HTTP semantics are honoured: GET is safe and idempotent, 4XX is a client error, 5XX is a server error. See Errors.

URLs and identifiers

A fixed major prefix /v2. Dated revisions are selected by header — see Versioning.
Resource collections are plural nouns (/patients, /sites, /practitioners).
IDs are strings carrying UUIDs (RFC 4122): 3fa85f64-5717-4562-b3fc-2c963f66afa6.

Field naming

Field names are snake_case (e.g. created_at, address_line_1, email_address).
Header names follow HTTP conventions (Authorization, X-Practice-Id, Dentally-API-Version).

Dates and times

All timestamps are ISO 8601 in UTC, with the trailing Z: 2025-08-12T11:00:00Z.
Time‑of‑day fields without a date use HH:MM (24‑hour) in the local time of the resource (for example a site's opening hours).
Calendar dates without a time use YYYY-MM-DD.

Nullability

Fields that are known to be absent are returned as null rather than omitted (e.g. address.address_line_2: null, opening_hours[].open_at: null for a closed day).
Required fields per the schema are always present.

Response envelopes

Single resource:

{ "data": { /* one object */ } }

List resource (always paginated):

{
  "data": [ /* array of objects */ ],
  "meta": { "cursor": "<opaque or null>" }
}

See Pagination for cursor handling.

Required headers

Header	When	Notes
`Authorization: Bearer <jwt>`	every request	See Authentication.
`Dentally-API-Version: <id>`	recommended on every request	See Versioning.
`X-Practice-Id: <uuid>`	practice‑scoped operations	Identifies the practice the request acts on.

Errors

Every non‑2xx response is a Problem Details body (RFC 7807). See Errors for the full envelope and standard responses.

Forward compatibility

New, optional request fields and headers may be added within a dated version. Reject unknown fields client‑side at your peril.
New response fields may be added within a dated version. Clients must ignore unknown response properties.
Breaking changes only ever ship as a new dated version — see Versioning.