---
title: "Get appointments"
method: GET
path: "/v1/appointments"
tags: ["appointments"]
---

# Get appointments

`GET /v1/appointments`

## Request

- Base URL: `https://api-developer-sandbox.zocdoc.com`
- URL: `https://api-developer-sandbox.zocdoc.com/v1/appointments`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `https://auth.zocdoc.com/oauth/token` scopes: `external.appointment.read`
  - OAuth 2
    - Authorization code: `https://auth.zocdoc.com/authorize`
    - Token URL: `https://auth.zocdoc.com/oauth/token` scopes: `external.appointment.read`

This endpoint retrieves the paginated list of appointment details and statuses for the given credential. By default, appointments will be returned in descending order of start time.

A maximum of 1,000 total appointments will be returned via pagination; if more are expected, use filters and batch requests.

If the request comes from a Zocdoc user credential, only appointments that user has created will be returned. If the request comes from a machine-to-machine credential, any appointments that were booked with that developer will be returned.

## Query parameters

- `page` integer
- `page_size` integer
- `statuses` string
- `developer_patient_id` string
- `sort_by` 'start_time_utc' | 'created_time_utc' | 'last_modified_time_utc': Field to sort appointments by: * start_time_utc - Sort by appointment start time (default) * created_time_utc - Sort by when appointment was created * last_modified_time_utc - Sort by when appointment was last modified
- `sort_direction` 'ascending' | 'descending'
- `practice_ids` string
- `provider_ids` string
- `location_ids` string
- `start_time_utc_min` string, instant
- `start_time_utc_max` string, instant
- `created_time_utc_min` string, instant
- `created_time_utc_max` string, instant
- `last_modified_time_utc_min` string, instant
- `last_modified_time_utc_max` string, instant

## Response `200`

Successful

- AppointmentStatusListResponse
  - `request_id` string, required: Unique request identifier for tracing
  - `page` integer, required: The zero based index of the current page.
  - `page_size` integer, required: The size of the current page.
  - `total_count` integer, required: The total number of result items.
  - `next_url` string, required: A link to the next page of results; null if this is the last page of results.
  - `data` AppointmentStatusResponseData[], required
    - `appointment_id` string, required: The Zocdoc ID of the appointment.
    - `appointment_status` 'pending_booking' | 'confirmed' | 'booking_failed' | 'cancelled' | 'no_show' | 'pending_reschedule' | 'rescheduled' | 'reschedule_failed', required: The status of the appointment. See [Appointment Status definitions](/guides/glossary).
    - `developer_patient_id` string: The patient identifier provided by 3P developer. Null if not provided.
    - `is_provider_resource` boolean, required: Whether the appointment will be performed by a professional under the supervision of the booked provider.
    - `location_phone_number` string: The appointment location's unformatted 10 digit phone number
    - `location_phone_extension` string: The appointment location's unformatted extension number, as digits
    - `waiting_room_path` string: Patient facing url that can be used to navigate to Zocdoc video service appointments
    - `confirmation_type` 'auto' | 'manual' | 'pending_evaluation', required: Specifies how the appointment confirmation will be handled. * auto: means the system will automatically confirm. * manual: means confirmation requires user action. * pending_evaluation: indicates that the confirmation approach is pending evaluation.
    - `start_time` string, date-time, required: Date & time of the appointment
    - `created_time_utc` string, instant: UTC date & time of the appointment creation
    - `last_modified_time_utc` string, instant: UTC date & time of the appointment last modification
    - `provider_location_id` string, required
    - `practice_id` string: The Zocdoc id of the practice
    - `visit_reason_id` string, required
    - `visit_type` 'in_person' | 'zocdoc_video_service' | 'third_party_video_service': The appointment's [visit type](/guides/glossary)
    - `patient_type` 'existing' | 'new': Whether or not the patient has been to the provider's practice.
    - `notes` string: Patient notes. 100 character maximum limit.
    - `cancellation_reason` string: Optional free text description for the appointment cancellation. Only use this field when cancellation_reason_type is set to 'other_patient_reason' or 'other_provider_reason'.
    - `source` string: The channel where the appointment was booked (e.g., "Zocdoc Marketplace", "Your website").

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden

---

[API](https://skmtc.dev/zocdoc/apis/zocdoc-bundle-api.md) - [All operations](https://skmtc.dev/zocdoc/apis/zocdoc-bundle-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zocdoc/apis/zocdoc-bundle-api/revisions/965a6ca4ed12?raw)