---
title: "List Appointments"
method: GET
path: "/api/2026-01-01/appointments"
tags: ["Appointments"]
---

# List Appointments

`GET /api/2026-01-01/appointments`

## Request

- Base URL: `https://jdpdocsdemo.jane.qa`
- URL: `https://jdpdocsdemo.jane.qa/api/2026-01-01/appointments`
- Auth: OAuth 2
  - Authorization code: `https://login.id.janeapp.com/realms/jane_partner_sandbox/protocol/openid-connect/auth?response_type=code&resource=https://jdpdocsdemo.jane.qa&prompt=consent`
  - Token URL: `https://login.id.janeapp.com/realms/jane_partner_sandbox/protocol/openid-connect/token` scopes: `appointments:read`

List Appointments. Returns one-on-one, group, and class bookings. The `booking_type` field distinguishes them, and group/class rows expose `capacity`, `participant_count`, and (via `_include=participants`) their participants. For class bookings `patient_id` is null.

Filtering:
Filter records by field values using the format: field[operator]=value

Available fields:
- `public_id`: string
- `start_at`: ISO 8601 datetime (e.g. 2025-01-01T12:00:00Z)
- `end_at`: ISO 8601 datetime
- `patient_id`: UUID String
- `staff_member_id`: UUID String
- `location_id`: UUID String
- `treatment_id`: UUID String
- `created_at`: ISO 8601 datetime
- `updated_at`: ISO 8601 datetime

Available operators:
- `eq`: Equals
- `gt`: Greater than
- `gte`: Greater than or equal
- `lt`: Less than
- `lte`: Less than or equal

Date-time filters (ex. `start_at`, `end_at`, `created_at`, `updated_at`) must:
- Use [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date-time format
- Be **precise to the second** (e.g. `2025-01-01T12:00:00Z`)

Examples:
```
/appointments?public_id[eq]=abc123
/appointments?created_at[gte]=2025-01-01T00:00:00Z&created_at[lt]=2025-01-02T00:00:00Z
```

## Query parameters

- `page[cursor]` string
- `page[limit]` integer
- `sort` string
- `public_id` StringFilterSchema
  - `eq` string: equals. Multiple equal values are comma-separated: ?field[eq]=value1,value2 (maximum 100 values)
  - `ne` string: not equals
  - `co` string: contains. Performs partial match (case-insensitive for string fields). Example: ?field[co]=search_term
  - `gt` string: greater than
  - `gte` string: greater than or equal to
  - `lt` string: less than
  - `lte` string: less than or equal to
  - `sw` string: starts with. Performs case-insensitive partial match for words in a string that begin with search term. Example: ?field[sw]=search_term
- `start_at` DateTimeFilterSchema
  - `eq` string, date-time: equals. Multiple equal values are comma-separated: ?field[eq]=value1,value2
  - `ne` string, date-time: not equals
  - `gt` string, date-time: greater than
  - `gte` string, date-time: greater than or equal to
  - `lt` string, date-time: less than
  - `lte` string, date-time: less than or equal to
- `end_at` DateTimeFilterSchema
  - `eq` string, date-time: equals. Multiple equal values are comma-separated: ?field[eq]=value1,value2
  - `ne` string, date-time: not equals
  - `gt` string, date-time: greater than
  - `gte` string, date-time: greater than or equal to
  - `lt` string, date-time: less than
  - `lte` string, date-time: less than or equal to
- `patient_id` IdFilterSchema
  - `eq` string: equals. Multiple equal values are comma-separated: ?field[eq]=value1,value2 (maximum 100 values)
- `staff_member_id` IdFilterSchema
  - `eq` string: equals. Multiple equal values are comma-separated: ?field[eq]=value1,value2 (maximum 100 values)
- `location_id` IdFilterSchema
  - `eq` string: equals. Multiple equal values are comma-separated: ?field[eq]=value1,value2 (maximum 100 values)
- `treatment_id` IdFilterSchema
  - `eq` string: equals. Multiple equal values are comma-separated: ?field[eq]=value1,value2 (maximum 100 values)
- `created_at` DateTimeFilterSchema
  - `eq` string, date-time: equals. Multiple equal values are comma-separated: ?field[eq]=value1,value2
  - `ne` string, date-time: not equals
  - `gt` string, date-time: greater than
  - `gte` string, date-time: greater than or equal to
  - `lt` string, date-time: less than
  - `lte` string, date-time: less than or equal to
- `updated_at` DateTimeFilterSchema
  - `eq` string, date-time: equals. Multiple equal values are comma-separated: ?field[eq]=value1,value2
  - `ne` string, date-time: not equals
  - `gt` string, date-time: greater than
  - `gte` string, date-time: greater than or equal to
  - `lt` string, date-time: less than
  - `lte` string, date-time: less than or equal to
- `_include` string

## Response `200`

The appointments

- AppointmentsResponse: Response to a request for multiple appointments
  - `items` Appointment[]: The list of appointments. Empty if there are none.
    - `id` string, uuid, required
    - `start_at` string, date-time
    - `end_at` string, date-time
    - `staff_member_id` string, uuid
    - `patient_id` string, uuid, nullable: The billing/primary patient. Present for one-on-one and group bookings; null for class bookings (which have participants instead of a single patient).
    - `location_id` string, uuid
    - `treatment_id` string, uuid
    - `room_id` string, uuid, nullable
    - `first_visit` boolean
    - `cancelled_at` string, date-time, nullable
    - `cancelled_reason` string, nullable: The reason the appointment was cancelled. Free-text reasons entered by staff are mapped to 'Other' to prevent exposure of potentially sensitive information; only predefined reasons are returned as-is.
    - `booked_at` string, date-time
    - `no_show_at` string, date-time, nullable
    - `arrived_at` string, date-time, nullable
    - `archived_at` string, date-time, nullable
    - `checked_in_at` string, date-time, nullable
    - `state` 'reserved' | 'booked' | 'arrived' | 'no_show' | 'cancelled' | 'archived': The current state of the appointment.
    - `booking_type` 'one_on_one' | 'group' | 'class' | 'null', nullable: The kind of booking. `one_on_one` is a single-patient appointment; `group` and `class` are multi-participant bookings (see `participants`). May be null for reserved appointments that have no treatment yet.
    - `capacity` integer: Maximum number of participants for the appointment's treatment. 1 for one-on-one bookings.
    - `participant_count` integer: Current number of active (non-cancelled, non-archived) participants.
    - `participants` Participant[]: The participants of a group/class booking. Only present when the request specifies `_include=participants`. For one-on-one bookings this is a single entry describing the appointment's own patient.
      - `patient_id` string, uuid, nullable: The participant's patient. May be null.
      - `state` 'reserved' | 'booked' | 'arrived' | 'no_show' | 'cancelled': The participant's current state. The internal `checked_in` state is surfaced as `booked`, matching the appointment `state`.
      - `arrived_at` string, date-time, nullable: When the participant arrived, or null.
      - `no_show_at` string, date-time, nullable: When the participant was marked no-show, or null.
      - `cancelled_at` string, date-time, nullable: When the participant was cancelled, or null.
  - `limit` integer: The number of appointments to return
  - `links` object: The links to the current and next pages of appointments
    - `after` string, nullable: URL for the next page of results. null if this is the last page.
  - `hasNextPage` boolean: Whether there is a next page of appointments
  - `cursor` string, nullable: The Base64 encoded cursor for the next page. null if this is the last page.
  - `included` IncludedResource[]: Sideloaded resources for the current page, deduplicated by `(type, id)`. Only present when the request specifies `_include`. See the endpoint's `_include` parameter for supported resource types and exposed attributes.
    - union: A sideloaded resource returned in the top-level `included` array when `_include` is requested. Discriminated on `type` so the generated client emits a narrowing union (e.g. `r.type === 'patient'` narrows `r.attributes` to the patient attribute shape). Use `const` rather than `enum` for the discriminator value — openapi-generator emits TS enums for enum values, which are nominal and break union narrowing.
      - object: A sideloaded patient returned in the top-level `included` array when `_include=patient` is requested.
        - `type` 'patient', required: Resource type discriminator.
        - `id` string, uuid, required: The public id of the sideloaded patient.
        - `attributes` object, required
          - `first_name` string, required
          - `last_name` string, required
          - `preferred_name` string, nullable
      - object: A sideloaded treatment returned in the top-level `included` array when `_include=treatment` is requested.
        - `type` 'treatment', required: Resource type discriminator.
        - `id` string, uuid, required: The public id of the sideloaded treatment.
        - `attributes` object, required
          - `name` string, required
          - `color` 'jane-blue' | 'butter' | 'lavender' | 'tangerine' | 'dusk' | 'moss' | 'lilac' | 'flamingo' | 'mint' | 'mauve', required: The treatment's display color, as a human-readable slug from a fixed palette of 10 values. Hex values for rendering: jane-blue: #00c1ca | butter: #efd59a | lavender: #c4c4d6 | tangerine: #f1b37a | dusk: #8eb8c9 | moss: #8ea785 | lilac: #d1a6c5 | flamingo: #e8a2b6 | mint: #a5d7c5 | mauve: #c38f92
      - object: A sideloaded room returned in the top-level `included` array when `_include=room` is requested.
        - `type` 'room', required: Resource type discriminator.
        - `id` string, uuid, required: The public id of the sideloaded room.
        - `attributes` object, required
          - `name` string, required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: A requested `_include` resource is not accessible with the supplied token's scopes
- `429`: Rate limit exceeded - 100 requests per minute per endpoint per clinic

## Changes

- **2026-11-03** `01798f613a5e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/jane/apis/jdp-api/changes/api/2026-01-01/appointments/get.md)

---

[API](https://skmtc.dev/jane/apis/jdp-api.md) - [All operations](https://skmtc.dev/jane/apis/jdp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/jane/apis/jdp-api/revisions/01798f613a5e?raw)