# Get appointments

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.


Endpoint: GET /v1/appointments
Version: 1.22
Security: ClientCredentialsFlow, AuthorizationCodeFlow

## Query parameters:

  - `page` (integer)
    The zero indexed page of results. A mimimum value of 0 and a maximum of 10 will be accepted.

  - `page_size` (integer)
    The number of results to return per page. A mimimum value of 1 and a maximum of 100 will be accepted.

  - `statuses` (string)
    A comma-delimited list of Zocodc appointment statuses to filter appointments by.
    Example: "pending_booking,confirmed"

  - `developer_patient_id` (string)
    The patient identifier provided by 3P developer to filter appointments by.

  - `sort_by` (string)
    The field to sort appointments by. Default is start_time.
    Enum: "start_time_utc", "created_time_utc", "last_modified_time_utc"

  - `sort_direction` (string)
    The direction to sort appointments by. Default is descending.
    Enum: "ascending", "descending"

  - `provider_ids` (string)
    The comma separated values of provider ids to filter appointments by
    Example: "pr_abc123-def456_wxyz7890,pr_ghi123-jkl456_mnop7890"

  - `location_ids` (string)
    The comma separated values of location ids to filter appointments by
    Example: "lo_abc123-def456_wxyz7890,lo_ghi123-jkl456_mnop7890"

  - `practice_ids` (string)
    The comma separated values of practice ids to filter appointments by
    Example: "pt_abc123-def456_wxyz7890,pt_ghi123-jkl456_mnop7890"

  - `start_time_utc_min` (string)
    The minimum UTC start time of the appointments to fetch. Exclude appointments that start before this time.
    Example: "2024-01-01T00:00:00Z"

  - `start_time_utc_max` (string)
    The maximum UTC start time of the appointments to fetch. Exclude appointments that start after this time.
    Example: "2024-01-01T00:00:00Z"

  - `created_time_utc_min` (string)
    The minimum UTC created time of the appointments to fetch. Exclude appointments that were created before this time.
    Example: "2024-01-01T00:00:00Z"

  - `created_time_utc_max` (string)
    The maximum UTC created time of the appointments to fetch. Exclude appointments that were created after this time.
    Example: "2024-01-01T00:00:00Z"

  - `last_modified_time_utc_min` (string)
    The minimum UTC last modified time of the appointments to fetch. Exclude appointments that were last modified before this time.
    Example: "2024-01-01T00:00:00Z"

  - `last_modified_time_utc_max` (string)
    The maximum UTC last modified time of the appointments to fetch. Exclude appointments that were last modified after this time.
    Example: "2024-01-01T00:00:00Z"

## Response 200 fields (application/json):

  - `request_id` (string, required)

  - `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` (array, required)

  - `data.appointment_id` (string, required)
    The Zocdoc ID of the appointment.

  - `data.appointment_status` (string, required)
    The status of the appointment. See [Appointment Status definitions](/guides/glossary).
    Enum: "pending_booking", "confirmed", "booking_failed", "cancelled", "no_show", "pending_reschedule", "rescheduled", "reschedule_failed"

  - `data.developer_patient_id` (string)

  - `data.is_provider_resource` (boolean, required)
    Whether the appointment will be performed by a professional under the supervision of the booked provider.

  - `data.location_phone_number` (string)
    The appointment location's unformatted 10 digit phone number
    Example: "9999999999"

  - `data.location_phone_extension` (string)
    The appointment location's unformatted extension number, as digits

  - `data.waiting_room_path` (string)
    Patient facing url that can be used to navigate to Zocdoc video service appointments

  - `data.confirmation_type` (string, 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.
    Enum: "auto", "manual", "pending_evaluation"

  - `data.start_time` (string, required)
    Date & time of the appointment
    Example: "2022-04-27T09:00:00-04:00"

  - `data.created_time_utc` (string)
    UTC date & time of the appointment creation
    Example: "2024-01-01T09:30:00Z"

  - `data.last_modified_time_utc` (string)
    UTC date & time of the appointment last modification
    Example: "2024-01-01T09:30:00Z"

  - `data.provider_location_id` (string, required)

  - `data.practice_id` (string)
    The Zocdoc id of the practice

  - `data.visit_reason_id` (string, required)

  - `data.visit_type` (string)
    The appointment's [visit type](/guides/glossary)
    Enum: "in_person", "zocdoc_video_service", "third_party_video_service"

  - `data.patient_type` (string)
    Whether or not the patient has been to the provider's practice.
    Enum: "existing", "new"

  - `data.notes` (string)
    Patient notes

  - `data.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'.

  - `data.cancellation_reason_type` (string)
    Enum field describing why the appointment was cancelled. This field is optional but recommended when known for metrics purposes. If the cancellation reason does not match any predefined enum values, use 'other_patient_reason' or 'other_provider_reason' and provide a free text explanation in the cancellation_reason field.
    Enum: "patient_no_longer_needs_appointment", "patient_no_longer_available", "other_patient_reason", "missing_needed_patient_information", "payment_or_insurance_issue", "patient_or_visit_type_not_accepted", "provider_not_available", "rescheduling_patient", "other_provider_reason"

## Response 400 fields (application/json):

  - `request_id` (string, required)

  - `error_type` (string, required)
    Enum: "api_error", "invalid_request"

  - `errors` (array, required)

  - `errors.field` (string)

  - `errors.message` (string, required)