Get appointments

Request

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.

Security

ClientCredentialsFlow(Required scopes: external.appointment.read) or AuthorizationCodeFlow(Required scopes: external.appointment.read)

Query

pageinteger

The zero indexed page of results. A mimimum value of 0 and a maximum of 10 will be accepted.

page_sizeinteger

The number of results to return per page. A mimimum value of 1 and a maximum of 100 will be accepted.

statusesstring

A comma-delimited list of Zocodc appointment statuses to filter appointments by.

Example:statuses=pending_booking,confirmed

developer_patient_idstring

The patient identifier provided by 3P developer to filter appointments by.

sort_bystring(AppointmentSortByType)

The field to sort appointments by. Default is start_time.

Enum:"start_time_utc""created_time_utc""last_modified_time_utc"

sort_directionstring(AppointmentSortDirectionType)

The direction to sort appointments by. Default is descending.

Enum:"ascending""descending"

practice_idsstring

The comma separated values of practice ids to filter appointments by

Example:practice_ids=pt_abc123-def456_wxyz7890,pt_ghi123-jkl456_mnop7890

provider_idsstring

The comma separated values of provider ids to filter appointments by

Example:provider_ids=pr_abc123-def456_wxyz7890,pr_ghi123-jkl456_mnop7890

location_idsstring

The comma separated values of location ids to filter appointments by

Example:location_ids=lo_abc123-def456_wxyz7890,lo_ghi123-jkl456_mnop7890

start_time_utc_minstring, (instant)

The minimum UTC start time of the appointments to fetch. Exclude appointments that start before this time.

Example:start_time_utc_min=2024-01-01 00:00:00+00:00

start_time_utc_maxstring, (instant)

The maximum UTC start time of the appointments to fetch. Exclude appointments that start after this time.

Example:start_time_utc_max=2024-01-01 00:00:00+00:00

created_time_utc_minstring, (instant)

The minimum UTC created time of the appointments to fetch. Exclude appointments that were created before this time.

Example:created_time_utc_min=2024-01-01 00:00:00+00:00

created_time_utc_maxstring, (instant)

The maximum UTC created time of the appointments to fetch. Exclude appointments that were created after this time.

Example:created_time_utc_max=2024-01-01 00:00:00+00:00

last_modified_time_utc_minstring, (instant)

The minimum UTC last modified time of the appointments to fetch. Exclude appointments that were last modified before this time.

Example:last_modified_time_utc_min=2024-01-01 00:00:00+00:00

last_modified_time_utc_maxstring, (instant)

The maximum UTC last modified time of the appointments to fetch. Exclude appointments that were last modified after this time.

Example:last_modified_time_utc_max=2024-01-01 00:00:00+00:00

curl -i -X GET \
  'https://api-developer-sandbox.zocdoc.com/v1/appointments?page=0&page_size=0&statuses=pending_booking%2Cconfirmed&developer_patient_id=string&sort_by=start_time_utc&sort_direction=ascending&practice_ids=pt_abc123-def456_wxyz7890%2Cpt_ghi123-jkl456_mnop7890&provider_ids=pr_abc123-def456_wxyz7890%2Cpr_ghi123-jkl456_mnop7890&location_ids=lo_abc123-def456_wxyz7890%2Clo_ghi123-jkl456_mnop7890&start_time_utc_min=2024-01-01%2000%3A00%3A00%2B00%3A00&start_time_utc_max=2024-01-01%2000%3A00%3A00%2B00%3A00&created_time_utc_min=2024-01-01%2000%3A00%3A00%2B00%3A00&created_time_utc_max=2024-01-01%2000%3A00%3A00%2B00%3A00&last_modified_time_utc_min=2024-01-01%2000%3A00%3A00%2B00%3A00&last_modified_time_utc_max=2024-01-01%2000%3A00%3A00%2B00%3A00' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful

Bodyapplication/json

request_idstringrequired

Unique request identifier for tracing

pageintegerrequired

The zero based index of the current page.

page_sizeintegerrequired

The size of the current page.

total_countintegerrequired

The total number of result items.

next_urlstringrequired

A link to the next page of results; null if this is the last page of results.

dataArray of objects(AppointmentStatusResponseData)required

Response

{
  "request_id": "string",
  "page": 0,
  "page_size": 0,
  "total_count": 0,
  "next_url": "string",
  "data": [
    { … }
  ]
}