Skip to content
/Calendar Zones

Calendar Zones

Scheduled, recurring blocks of diary time reserved for a specific purpose, for a practitioner or a room. List and retrieve calendar zone occurrences, including their practitioner, room, and zone group.

Operations

List calendar zones

Request

Returns a paginated list of calendar zones for the practice identified by X-Practice-Id. A calendar zone is one occurrence of a scheduled, recurring block of diary time reserved for a specific purpose, for a practitioner or a room.

Required query parameters: date_from and date_to (inclusive, YYYY-MM-DD). Calendar zones that overlap the window are returned: a calendar zone is included when it starts on or before the end of date_to and finishes on or after the start of date_from. Past and future dates are accepted. date_to must be on or after date_from, and the window must not exceed 90 days; otherwise the API responds with 422.

When practitioner_id is supplied, only calendar zones scheduled for that practitioner are returned. A practitioner_id that is not a valid UUID results in 422.

Results are ordered by start time and ID, earliest first (start_time ascending, then id ascending). Use limit and the meta.cursor value from the response to retrieve further pages.

Note: calendar zones were known as session appointments (session_appointments) in the previous API version.

Security
oauth2(Required scopes: calendar:read)
Query
limitinteger, [ 1 .. 100 ]

Maximum number of records to return per page.

Default:20
cursorstring

Cursor reference to the next page of records.

date_fromstring, (date)required

Inclusive start of a required date range filter (YYYY-MM-DD). Pair with date_to. Specific range limits and matching rules are defined per endpoint.

Example:date_from=2025-01-01
date_tostring, (date)required

Inclusive end of a required date range filter (YYYY-MM-DD). Pair with date_from. Specific range limits and matching rules are defined per endpoint.

Example:date_to=2025-03-31
practitioner_idstring, (uuid)

Filter records to those associated with the specified practitioner. The value should be a UUID corresponding to a practitioner within the practice.

created_date_fromstring, (date)

Inclusive start of a created date range filter. Calendar date only (YYYY-MM-DD). Use together with created_date_to for explicit date range control.

  • When used together with created_date_to, the range between the two values must not exceed 90 days.
  • When used without created_date_to, returns records from created_date_from up to 90 days later (or up to the current date-time if it is earlier).
Example:created_date_from=2026-01-01
created_date_tostring, (date)

Inclusive end of a created date range filter. Calendar date only (YYYY-MM-DD). Use together with created_date_from for explicit date range control.

  • When used together with created_date_from, the range between the two values must not exceed 90 days.
  • When used without created_date_from, returns records from 90 days before created_date_to (or from the earliest available date if less than 90 days of data exists) up to created_date_to.
Example:created_date_to=2026-01-01
updated_date_fromstring, (date)

Inclusive start of an updated date range filter. Calendar date only (YYYY-MM-DD). Use together with updated_date_to for explicit date range control.

  • When used together with updated_date_to, the range between the two values must not exceed 90 days.
  • When used without updated_date_to, returns records from updated_date_from up to 90 days later (or up to the current date-time if it is earlier).
Example:updated_date_from=2026-01-01
updated_date_tostring, (date)

Inclusive end of an updated date range filter. Calendar date only (YYYY-MM-DD). Use together with updated_date_from for explicit date range control.

  • When used together with updated_date_from, the range between the two values must not exceed 90 days.
  • When used without updated_date_from, returns records from 90 days before updated_date_to (or from the earliest available date if less than 90 days of data exists) up to updated_date_to.
Example:updated_date_to=2026-01-01
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.

curl -i -X GET \
  'https://docs.api.dentally.com/_mock/docs/versions/2026-01-01/nexgen/calendar_zones?limit=20&cursor=string&date_from=2025-01-01&date_to=2025-03-31&practitioner_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&created_date_from=2026-01-01&created_date_to=2026-01-01&updated_date_from=2026-01-01&updated_date_to=2026-01-01' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'X-Practice-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Responses

Paginated list of calendar zones for the requested practice.

Bodyapplication/json
dataArray of objects(calendar-zone)required

Calendar zones in the current page.

metaobject(meta)required

Cursor-based pagination metadata. When an operation supports paging, pass cursor from this object on a subsequent request to continue after the current page.

Response

Paginated list with a cursor for the next page.

{
  "data": [
    { … },
    { … }
  ],
  "meta": {
    "cursor": "eyJjdXJzb3IiOiJuZXh0In0"
  }
}