Skip to content

Find Provider Availability and Book Appointments

Before using this guide you will need a developer account and an access token. You can contact us about creating a developer account here. To get an access token, review the authentication and access tokens guide.

1. Get NPIs

First you need to retrieve the list of active provider NPIs within your Zocdoc directory.

A Zocdoc directory is a developer-managed list of Zocdoc providers. Each developer account has at least one directory, and multiple directories can be created if needed to support your specific API use case.

The primary purpose of a directory is to define which providers are available for booking through your application. You can also use directories to explore the Zocdoc marketplace and identify providers you may want to include in your bookable directory.

curl -i -X GET \
  'https://api-developer-sandbox.zocdoc.com/v1/reference/npi?page=0&page_size=60000' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

2. Get provider information

There are three ways to retrieve provider-specific information:

Search by NPI

NPIs retrieved in the previous step can be used to fetch detailed provider information, including name, gender identity, spoken languages, specialties, visit reasons, and affiliated locations. Up to 50 NPIs can be queried in a single request.

curl -i -X GET \
  'https://api-developer-sandbox.zocdoc.com/v1/providers?npis=1234567891%2C0123456789&insurance_plan_id=ip_2224' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Search by ZIP and specialty or visit reason

If you don’t have NPIs, you can search by ZIP code and specialty or visit reason to find providers. This is beneficial when looking by distance or specifc reason.

curl -i -X GET \
  'https://api-developer-sandbox.zocdoc.com/v1/provider_locations?zip_code=36925&specialty_id=sp_153&visit_reason_id=pc_FRO-18leckytNKtruw5dLR&page=0&page_size=10&insurance_plan_id=ip_2224&visit_type=all&max_distance_to_patient_mi=50' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Search by provider location

You can also retrieve provider information using specific provider_location_ids. This is useful for patients who want to see a specific doctor at a specific location.

curl -i -X GET \
  'https://api-developer-sandbox.zocdoc.com/v1/provider_locations/pr_abc123-def456_wxyz7890|lo_abc123-def456_wxyz7890?insurance_plan_id=ip_2224' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

3. Get availability

Using a specific provider_location_id, visit_reason_id, and patient_type, you can retrieve the provider's availability.

start_date_in_provider_local_time defaults to current date in US Eastern Time. YYYY-MM-DD format.

end_date_in_provider_local_time defaults to 7 days after the current date. Must be 30 days or less after the start date. You can request availability up to a maximum of 150 days into the future.

curl -i -X GET \
  'https://api-developer-sandbox.zocdoc.com/v1/provider_locations/availability?provider_location_ids=pr_abc123-def456_wxyz7890%7Clo_abc123-def456_wxyz7890%2Cpr_ghi123-jkl456_mnop7890%7Clo_ghi123-jkl456_mnop7890&visit_reason_id=pc_FRO-18leckytNKtruw5dLR&patient_type=new&start_date_in_provider_local_time=2019-08-24&end_date_in_provider_local_time=2019-08-24' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

4. Book an appointment

Using an available start_time you can create an appointment for the patient. This will return an appointment_id which can be used to confirm, cancel, or reschedule the appointment.

appointment_typestring(AppointmentType)required

The type of appointment.

Value"providers"
dataobject(AppointmentData)required
data.​start_timestring(date-time)required

Date & time of the appointment in ISO-8601 format with a timezone offset. Must be a valid start time from the /v1/provider_locations/availability endpoint.

Example: "2022-04-27T09:00:00-04:00"
data.​visit_reason_idstringrequired

The Zocdoc visit reason ID for the appointment. Must be accepted by the provider.

Example: "pc_FRO-18leckytNKtruw5dLR"
data.​provider_location_idstringrequired

The Zocdoc provider-location ID for the appointment.

Example: "pr_abc123-def456_wxyz7890|lo_abc123-def456_wxyz7890"
data.​patientobject(Patient)required
data.​patient.​patient_idstring

The Zocdoc ID of the patient.

data.​patient.​developer_patient_idstring

The patient identifier provided by 3P developer.

data.​patient.​first_namestring<= 50 charactersrequired

The patient's first name.

data.​patient.​last_namestring<= 50 charactersrequired

The patient's last name.

data.​patient.​date_of_birthstring(date)required

The patient's date of birth in the format, YYYY-MM-DD.

data.​patient.​sex_at_birthstring(PatientSex)required

The patient's sex assigned at birth.

Enum"male""female"
data.​patient.​phone_numberstring<= 10 charactersrequired

The patient's unformatted 10 digit phone number. The first and fourth digits cannot be a 0 or 1.

Example: "9999999999"
data.​patient.​email_addressstring<= 255 charactersrequired

The patient's email address.

Example: "test@example.com"
data.​patient.​patient_addressobject(PatientAddress)required
data.​patient.​patient_address.​address1string<= 50 charactersrequired

The patient's address, line 1.

data.​patient.​patient_address.​citystring<= 50 charactersrequired

The patient's address, city.

data.​patient.​patient_address.​statestring<= 2 charactersrequired

The patient's address, two letter state code.

Example: "NY"
data.​patient.​patient_address.​zip_codestringrequired

The patient's address, 5 digit zip code.

Example: 36925
data.​patient.​patient_address.​address2string<= 20 characters

The patient's address, line 2.

data.​patient.​insuranceobject(PatientInsurance)
data.​patient.​genderArray of strings(Gender)

none_apply and prefer_not_to_say must be used independently, all other gender identities can be used in combination with each other.

Items Enum"female_at_birth""male_at_birth""cisgender""genderfluid""genderqueer""intersex""non_binary""transgender_man""transgender_woman""prefer_not_to_say"
data.​patient_typestring(PatientType)required

Whether or not the patient has been to the provider's practice.

Enum"existing""new"
Example: "new"
data.​notesstring<= 100 characters

Patient notes

curl -i -X POST \
  https://api-developer-sandbox.zocdoc.com/v1/appointments \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "appointment_type": "providers",
    "data": {
      "start_time": "2022-04-27T09:00:00-04:00",
      "visit_reason_id": "pc_FRO-18leckytNKtruw5dLR",
      "provider_location_id": "pr_abc123-def456_wxyz7890|lo_abc123-def456_wxyz7890",
      "patient": {
        "patient_id": "string",
        "developer_patient_id": "string",
        "first_name": "string",
        "last_name": "string",
        "date_of_birth": "2019-08-24",
        "sex_at_birth": "male",
        "phone_number": "9999999999",
        "email_address": "test@example.com",
        "patient_address": {
          "address1": "string",
          "city": "string",
          "state": "NY",
          "zip_code": 36925,
          "address2": "string"
        },
        "insurance": {
          "insurance_plan_id": "ip_2224",
          "insurance_group_number": "string",
          "insurance_member_id": "string",
          "is_self_pay": true
        },
        "gender": [
          "female_at_birth"
        ]
      },
      "patient_type": "new",
      "notes": "string"
    }
  }'
Copyright © Zocdoc Inc. All rights reserved.