---
title: "Get availability for provider locations"
method: GET
path: "/v1/provider_locations/availability"
tags: ["provider-locations"]
---

# Get availability for provider locations

`GET /v1/provider_locations/availability`

## Request

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

Retrieves availability for a set of provider locations. Required parameters passed include provider location ids, visit reason id and patient type. Visit reason and patient type (new or existing) are used to calculate the duration of the appointment and break availability into bookable timeslots based on the appointment duration. The response output includes the start times of appointments based on these calculations.

The `start_time` returned is used in the endpoint /v1/appointments to book appointments.
If no timeslots are available that satisfy the parameters, an empty array will be returned for that Provider Location's timeslots.

## Query parameters

- `provider_location_ids` string, required
- `visit_reason_id` string, required
- `patient_type` 'existing' | 'new', required: Whether or not the patient has been to the provider's practice.
- `start_date_in_provider_local_time` string, date
- `end_date_in_provider_local_time` string, date
- `published_context` 'direct_listing' | 'condition_driven_search'
- `insurance_plan_id` string
- `insurance_carrier_id` string

## Response `200`

Successful

- AvailabilityResult
  - `request_id` string, required: Unique request identifier for tracing
  - `data` Availability[]: Response containing the availaibility information.
    - `provider_location_id` string: The Zocdoc provider location ID for the availability.
    - `first_availability` Timeslot
      - `start_time` string, date-time, required: Date & time of the appointment in ISO-8601 format with a timezone offset. The timezone offset will be the provider's local time zone.
      - `visit_reason_id` string: The Zocdoc ID of the visit reason this timeslot is valid for.
      - `booking_url` string: Non-PHI deep link URL that allows developers to book this specific timeslot on zocdoc.com. Utm parameters (utm_medium=partnersynd and utm_source={appClientId}) will be automatically added. Developers will not be able to see the result of the booking.
    - `timeslots` Timeslot[]
      - `start_time` string, date-time, required: Date & time of the appointment in ISO-8601 format with a timezone offset. The timezone offset will be the provider's local time zone.
      - `visit_reason_id` string: The Zocdoc ID of the visit reason this timeslot is valid for.
      - `booking_url` string: Non-PHI deep link URL that allows developers to book this specific timeslot on zocdoc.com. Utm parameters (utm_medium=partnersynd and utm_source={appClientId}) will be automatically added. Developers will not be able to see the result of the booking.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict

---

[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)