# Get availability for provider locations

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  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.


Endpoint: GET /v1/provider_locations/availability
Version: 1.22
Security: ClientCredentialsFlow, AuthorizationCodeFlow

## Query parameters:

  - `provider_location_ids` (string, required)
    A comma-delimited list of Zocdoc  retrieved from the /v1/providers or /v1/provider_locations endpoint. A maximum of 50 items will be accepted at a time.
    Example: "pr_abc123-def456_wxyz7890|lo_abc123-def456_wxyz7890,pr_ghi123-jkl456_mnop7890|lo_ghi123-jkl456_mnop7890"

  - `visit_reason_id` (string, required)
    The Zocdoc ID of the visit reason. See Reference Data for options.
    Example: "pc_FRO-18leckytNKtruw5dLR"

  - `patient_type` (string, required)
    New or existing to indicate if the patient is new to the practice or has been to the office before.
    Enum: "existing", "new"

  - `start_date_in_provider_local_time` (string)
    The first date to retrieve availability for, as YYYY-MM-DD. Defaults to current date in US Eastern Time. Can request availability up to a maximum of 150 days into the future.

  - `end_date_in_provider_local_time` (string)
    The last inclusive date to retrieve availability for, as YYYY-MM-DD. Defaults to 7 days after the current date. Must be 31 days or less after the start date.

## Response 200 fields (application/json):

  - `request_id` (string, required)

  - `data` (array)
    Response containing the availaibility information.

  - `data.provider_location_id` (string)
    The Zocdoc provider location ID for the availability.
    Example: "pr_abc123-def456_wxyz7890|lo_abc123-def456_wxyz7890"

  - `data.first_availability` (object)

  - `data.first_availability.start_time` (string, 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.
    Example: "2022-04-27T09:00:00-04:00"

  - `data.first_availability.visit_reason_id` (string)
    The Zocdoc ID of the visit reason this timeslot is valid for.
    Example: "pc_FRO-18leckytNKtruw5dLR"

  - `data.first_availability.booking_url` (string)
    Non-PHI deep link URL that allows developers to book this specific timeslot on zocdoc.com. Developers can append insurance parameters (insuranceCarrier and insurancePlan) as needed. These are numeric id values, and can be found in the insurance reference data files (ip_{numericId} and ic_{numericId}). 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.

  - `data.timeslots` (array)

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

## Response 403 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)

## Response 404 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)