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

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

## Query parameters:

  - `provider_location_ids` (string, required)
    A comma-delimited list of Zocdoc `provider_location_ids` retrieved from the /v1/providers or /v1/provider_locations endpoint. A maximum of 50 items will be accepted at a time.

  - `visit_reason_id` (string, required)
    The Zocdoc ID of the visit reason. See [Reference Data](/guides/reference-data) for options.

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

  - `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. 150 days into the future is the guaranteed maximum. Dates past 150 days may be accepted but are not supported.

  - `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 30 days or less after the start date. Both dates are included, so the maximum span is 31 days.

  - `published_context` (string)
    Determines how availability slots are returned. Direct_listing returns all slots, while condition_driven_search limits results to Zocdoc-active providers with budget. Applicable to syndication clients.

  - `insurance_plan_id` (string)
    The Zocdoc ID of the patient's insurance plan. Use the [Get Insurance Plans](#operation/getInsurancePlans) endpoint to retrieve available plans. Used to construct booking_url.

  - `insurance_carrier_id` (string)
    The Zocdoc ID of the patient's insurance carrier. See [Reference Data](/guides/reference-data) for options. Used to construct booking_url.

## Response 200 fields (application/json):

  - `request_id` (string, required)
    Unique request identifier for tracing

  - `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. 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.
    Example: https://www.zocdoc.com/booking/start?startTime=638874819000000000&locationId=274383&procedureId=75&professionalId=405844

  - `data.timeslots` (array)

## Response 400 fields (application/json):

  - `request_id` (string, required)
    Unique request identifier for tracing

  - `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)
    Unique request identifier for tracing

  - `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)
    Unique request identifier for tracing

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

  - `errors` (array, required)

  - `errors.field` (string)

  - `errors.message` (string, required)

## Response 409 fields (application/json):

  - `request_id` (string, required)
    Unique request identifier for tracing

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

  - `errors` (array, required)

  - `errors.field` (string)

  - `errors.message` (string, required)