# Get calendar zone by ID

Returns the single calendar zone matching `id` for the practice identified
by `X-Practice-Id`. The identifier is the same `id` returned when listing
calendar zones.
If no calendar zone exists for that practice and `id`, the API responds
with 404.
**Note:** calendar zones were known as session appointments
(`session_appointments`) in the previous API version.

Endpoint: GET /calendar_zones/{id}
Version: 2026-01-01
Security: oauth2

## Security:

  - `oauth2` (unknown)
    oauth2 scopes: calendar:read

## Path parameters:

  - `id` (string, required)
    Resource identifier to filter/find.

## Header parameters:

  - `X-Practice-Id` (string, 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.

## Response 200:

  - `200` (unknown)
    Full details for one calendar zone.

## Response 200 fields (application/json):

  - `data` (object, required)
    A calendar zone: one occurrence of a scheduled, recurring block of diary time reserved for a specific purpose, for a practitioner or a room. Calendar zones do not restrict which appointments can be booked within them.

  - `data.id` (string, required)
    Unique identifier for the calendar zone.
    Example: 9b2f4c1e-3d5a-4e8b-a7c6-1f2e3d4c5b6a

  - `data.title` (string, required)
    Title of the calendar zone, as shown in the practice diary.
    Example: Emergency slots

  - `data.start_time` (string, required)
    Start time of the calendar zone in ISO 8601 format in UTC.
    Example: 2026-01-05T09:00:00Z

  - `data.finish_time` (string, required)
    Finish time of the calendar zone in ISO 8601 format in UTC.
    Example: 2026-01-05T12:00:00Z

  - `data.practitioner` (object, required)
    The practitioner the calendar zone is scheduled for. Null when the calendar zone is scheduled for a room instead. Retrieve the full practitioner record for additional details.

  - `data.practitioner.id` (string, required)
    Unique identifier of the practitioner.
    Example: 550e8400-e29b-41d4-a716-446655440003

  - `data.practitioner.name` (string)
    Full display name of the practitioner.
    Example: Dr. John Smith

  - `data.room_id` (string, required)
    Identifier of the room the calendar zone is scheduled for, if applicable.
    Example: 550e8400-e29b-41d4-a716-446655440004

  - `data.zone_group` (object, required)
    The zone group the calendar zone belongs to, if any. Zone groups are practice-defined labels that group related calendar zones together.

  - `data.zone_group.id` (string, required)
    Unique identifier of the zone group.
    Example: 0f8fad5b-d9cb-469f-a165-70867728950e

  - `data.zone_group.name` (string, required)
    Display name of the zone group.
    Example: New patient exams

  - `data.created_at` (string, required)
    When the calendar zone was created (UTC, ISO 8601). Null for some older calendar zones.
    Example: 2025-12-01T10:15:00Z

  - `data.updated_at` (string, required)
    When the calendar zone was last updated (UTC, ISO 8601). Null for some older calendar zones.
    Example: 2025-12-01T10:15:00Z

## Response 400:

  - `400` (unknown)
    Malformed Request ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 400 fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 401:

  - `401` (unknown)
    Unauthorized - Provide proof of identity ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 401 fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 404:

  - `404` (unknown)
    Not Found - Could not find a matching entity ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 404 fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 4XX:

  - `4XX` (unknown)
    User Error ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 4XX fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 5XX:

  - `5XX` (unknown)
    Server Error ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 5XX fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 200 examples:

  - `Single calendar zone` (unknown)
    One calendar zone scheduled for a practitioner.

## Response 400 examples:

  - `Malformed or invalid request` (unknown)
    RFC 7807 problem details when validation fails (e.g. missing required field).

## Response 401 examples:

  - `Missing or invalid credentials` (unknown)
    RFC 7807 problem details when the caller is not authenticated.

## Response 404 examples:

  - `Resource not found` (unknown)
    RFC 7807 problem details when no resource matches the given identifier.

## Response 4XX examples:

  - `Generic client error response` (unknown)
    RFC 7807 problem details for a generic client error (e.g. conflict, unsupported media type).

## Response 5XX examples:

  - `Unexpected server error` (unknown)
    RFC 7807 problem details for an internal failure.