# Returns a list of Appointments (V1) based on filter criteria

**Query shape:** Prefer a **narrow** filter—combine `patient.id`, `provider.id`, or `location.id` with `lastModified` or date bounds where possible. A very wide date range with no other scoping can **408** (timeout) on large tenants; retry with a smaller window or use cursor pagination (`lastId` with `lastModified`—see parameter descriptions).
**Empty results:** **200** with `data: []` means no appointments matched; it does not indicate invalid filter values.
**responseFields:** Use only names allowed on this operation (see the `responseFields` parameter). Use `ALL` or the documented flat field list.
**Pagination:** The `page` query parameter is deprecated; **`lastModified` / `lastId`** style pagination is preferred.

Endpoint: GET /v1/appointments
Version: 191.0.3
Security: bearerAuth, oAuthSandbox

## Security:

  - `bearerAuth` (unknown)
    http bearer JWT

  - `oAuthSandbox` (unknown)
    oauth2

## Query parameters:

  - `responseFields` (string)
    A URL-encoded, comma-delimited list of field names to include in the response data. Additionally, the following values are also supported:

ALL - Returns all field names.

  - `filter` (string)
    Filter clauses for appointments (V1). General grammar and operators: the Public API filter documentation.
**Auto filter:** If you omit a date-limiting filter (such as `lastModified`), the server may apply one automatically; behavior can vary by deployment.
**Keys and operators (this endpoint)**
- `id` (`->`)
- `needsFollowUp` (`==`, `!=`)
- `status` (`==`, `!=`) — values include `LATE`, `HERE`, `READY`, `CHAIR`, `COMPLETED`, `CONFIRMED`, `UNCONFIRMED`, `NO_SHOW`, `BROKEN`, `LEFT_MESSAGE`, `CHECKOUT`, `WILL_CALL`, `UNREACHABLE`, `CANCELLEDBYOFFICE`
- `patient.id` (`==`, `!=`)
- `operatory.id` (`==`, `!=`, `->`)
- `location.id` (`==`, `!=`, `->`) — use `ALL` or `*` for all locations; `->["ALL"]` or `->["*"]` for explicit all-locations. Omitting `location.id` may default to all locations during a transitional period; it may become required (IDs or `["ALL"]`).
- `provider.id` (`==`, `!=`, `->`)
- `asap` (`==`)
- `start` (`>`, `<`, `>=`, `<=`)
- `lastModified` (`>`, `<`, `>=`, `<=`)

**Ordering:** When filtering by `start` or `lastModified`, use `lastId` with those filters for stable pagination; result order follows server rules for the chosen filters.
Examples: `patient.id==12345`, `provider.id==7`, `location.id==12`, `start>=2022-01-01`, `operatory.id==12`.

  - `page` (string)
    Page number for pagination control

  - `pageSize` (string)
    Page size for pagination control

  - `lastId` (string)
    the biggest appointmentId from previous page

## Header parameters:

  - `Organization-ID` (string, required)
    Organization context for the request. Must match the organization authorized by the access token.

## Response 200:

  - `200` (unknown)
    The request was successful

## Response 200 fields (application/json):

  - `data` (array)

  - `data.confirmed` (string)
    Example: 2024-05-02T16:30:00.000Z

  - `data.needsFollowUp` (boolean)
    Example: true

  - `data.followedUpOn` (string)
    Example: 2024-05-09T17:00:00.000Z

  - `data.start` (string, required)
    Example: 2024-05-09T12:00:00.000Z

  - `data.bookingType` (string)
    Enum: "TREATMENT", "RECARE", "NEW_PATIENT", "EXISTING_PATIENT"

  - `data.needsPremedicate` (boolean)
    Example: true

  - `data.note` (string)
    Example: string

  - `data.other` (string)
    Example: string

  - `data.bookedOnline` (boolean)
    Example: true

  - `data.leftMessage` (string)
    Example: 2024-05-02T00:00:00.000Z

  - `data.duration` (integer)
    Example: 1440

  - `data.asap` (boolean)
    Example: true

  - `data.lastModified` (string)
    Example: 2024-05-09T13:30:00.000Z

  - `data.labCaseDentalLab` (object)
    A reference to a linked model. Includes the id, the type and url at which the model can be accessed. Setting this field to null is going to set all labCase fields to null (labCaseStatus, labCaseDueDate, labCaseNote)

  - `data.labCaseDentalLab.id` (integer)

  - `data.labCaseDentalLab.type` (string)
    Example: string

  - `data.labCaseDentalLab.url` (string)
    Example: string

  - `data.labCaseStatus` (string)
    Enum: "OUTSTANDING", "RECEIVED"

  - `data.labCaseDueDate` (string)
    Example: 2024-05-09T17:00:00.000Z

  - `data.labCaseNote` (string)
    Example: string

  - `data.patientProcedures` (array)

  - `data.patientProcedures.id` (integer, required)
    The unique identifier for the linked model.
    Example: 12345

  - `data.patientProcedures.type` (string)
    The type of the linked model. This field is read-only.
    Example: ExampleModelType

  - `data.patientProcedures.url` (string, required)
    The URL at which the linked model can be accessed. This field is read-only.
    Example: https://api.example.com/models/12345

  - `data.practiceProcedures` (array)

  - `data.practiceProcedures.id` (integer, required)
    The unique identifier for the linked model.
    Example: 12345

  - `data.practiceProcedures.type` (string)
    The type of the linked model. This field is read-only.
    Example: ExampleModelType

  - `data.practiceProcedures.url` (string, required)
    The URL at which the linked model can be accessed. This field is read-only.
    Example: https://api.example.com/models/12345

  - `data.visits` (array)

  - `data.visits.id` (integer, required)
    The unique identifier for the linked model.
    Example: 12345

  - `data.visits.type` (string)
    The type of the linked model. This field is read-only.
    Example: ExampleModelType

  - `data.visits.url` (string, required)
    The URL at which the linked model can be accessed. This field is read-only.
    Example: https://api.example.com/models/12345

  - `data.id` (integer)

  - `data.end` (string)
    Example: 2024-05-09T13:00:00.000Z

  - `data.created` (string)
    Example: 2024-05-09T13:05:00.000Z

  - `data.status` (string, required)
    Enum: "LATE", "HERE", "READY", "CHAIR", "COMPLETED", "WILL_CALL", "CONFIRMED", "UNCONFIRMED", "NO_SHOW", "BROKEN", "LEFT_MESSAGE", "CHECKOUT", "UNREACHABLE", "CANCELLEDBYOFFICE"

  - `data.statusId` (number)

  - `data.timePattern` (object)
    Used to represent who is providing care to the patient during the appointment.

  - `data.timePattern.duration` (integer)
    Example: 1440

  - `data.timePattern.blocksPerHour` (integer)
    Example: 6

  - `data.timePattern.rows` (array)

  - `data.timePattern.rows.activity` (string)
    Enum: "assistant", "provider", "chair", "none"

  - `data.timePattern.rows.order` (integer)
    Example: 1

  - `data.provider` (object, required)
    A reference to a linked model. Includes the id, the type, and URL at which the model can be accessed.

  - `data.provider.id` (integer, required)
    The unique identifier for the linked model.
    Example: 12345

  - `data.provider.type` (string)
    The type of the linked model. This field is read-only.
    Example: ExampleModelType

  - `data.provider.url` (string, required)
    The URL at which the linked model can be accessed. This field is read-only.
    Example: https://api.example.com/models/12345

  - `data.otherProvider` (object)
    A reference to a linked model. Includes the id, the type, and URL at which the model can be accessed.

  - `data.otherProvider.id` (integer, required)
    The unique identifier for the linked model.
    Example: 12345

  - `data.otherProvider.type` (string)
    The type of the linked model. This field is read-only.
    Example: ExampleModelType

  - `data.otherProvider.url` (string, required)
    The URL at which the linked model can be accessed. This field is read-only.
    Example: https://api.example.com/models/12345

  - `data.patient` (object, required)
    A reference to a linked model. Includes the id, the type, and URL at which the model can be accessed.

  - `data.patient.id` (integer, required)
    The unique identifier for the linked model.
    Example: 12345

  - `data.patient.type` (string)
    The type of the linked model. This field is read-only.
    Example: ExampleModelType

  - `data.patient.url` (string, required)
    The URL at which the linked model can be accessed. This field is read-only.
    Example: https://api.example.com/models/12345

  - `data.operatory` (object, required)
    A reference to a linked model. Includes the id, the type, and URL at which the model can be accessed.

  - `data.operatory.id` (integer, required)
    The unique identifier for the linked model.
    Example: 12345

  - `data.operatory.type` (string)
    The type of the linked model. This field is read-only.
    Example: ExampleModelType

  - `data.operatory.url` (string, required)
    The URL at which the linked model can be accessed. This field is read-only.
    Example: https://api.example.com/models/12345

  - `warnings` (array)

  - `warnings.code` (string)

  - `warnings.title` (string)

  - `warnings.description` (string)

  - `warnings.source` (string)

  - `errors` (array)

  - `meta` (object)

  - `meta.pagination` (object)
    Pagination info
    Example: {"limit":10,"offset":0}

  - `meta.pagination.limit` (integer)
    Example: 10

  - `meta.pagination.offset` (integer)
    Example: 0

  - `meta.pagination.total` (integer)
    Example: 100

## Response 400:

  - `400` (unknown)
    The request was invalid or cannot be processed

## Response 401:

  - `401` (unknown)
    Authentication is required and has failed or has not been provided

## Response 403:

  - `403` (unknown)
    The request is understood, but it has been refused or access is not allowed

## Response 404:

  - `404` (unknown)
    The requested resource is either missing or does not exist

## Response 408:

  - `408` (unknown)
    The server timed out while processing the request

## Response 429:

  - `429` (unknown)
    Rate limit exceeded

## Response 500:

  - `500` (unknown)
    An unexpected error occurred

## Response 200 examples:

  - `default` (unknown)