Create Timeslots

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=0' \
  -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&latitude=-90&longitude=-180' \
  -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=0&insurance_plan_id=ip_2224&visit_type=all&max_distance_to_patient_mi=0' \
  -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. Create a provider's timeslots

Using the location_id and provider_id you can set all slots for a given provider and date, replacing any existing slots. Submitting an empty request body will remove all slots for the given date. Ensure all open timeslots are included in the array for each date, per request. Subsequent requests for a single date will override previous data.

UTC and IANA

time_zone must be a valid IANA timezone.

timeslotsArray of objects(TimeslotBaseRequest)[ 0 .. 1500 ] itemsrequired

timeslots[].provider_idstringrequired

Provider id

Example: "pr_abc123-def456_wxyz7890"

timeslots[].location_idstringrequired

Location id

Example: "lo_abc123-def456_wxyz7890"

timeslots[].start_timestring(date-time-local)required

the local date and time within the timezone. The seconds may be omitted.

Example: "2024-10-16T09:30:00"

timeslots[].time_zonestringrequired

The IANA time zone id of the appointment. Must be valid.

Example: "America/New_York"

timeslots[].allowed_visit_reason_idsArray of strings

Restrict the timeslot to these visit reasons. Both null and an empty array will not restrict the timeslot.

Can work in conjunction with excluded_visit_reason_ids. allowed_visit_reason_ids are superceded by excluded_visit_reason_ids. So if a visit reason is included in both allowed_visit_reason_ids and excluded_visit_reason_ids, the net effect is that visit reason being excluded.

allowed	excluded	=> Result
null	null	all visit reasons allowed
[A,B]	null	only A & B are allowed
null	[A,B]	all visit reasons except A & B are allowed
[A,B]	[B,C]	only A is allowed (C is irrelevant)
[A,B]	[A,B]	No visit reasons allowed, unbookable timeslot

Example: ["pc_TlZW-r06U0W3pCsIGtSI5B"]

timeslots[].excluded_visit_reason_idsArray of strings

Exclude these visit reasons. Both null and an empty array means no visit reasons will be excluded.

Can work in conjunction with allowed_visit_reason_ids. allowed_visit_reason_ids are superceded by excluded_visit_reason_ids. So if a visit reason is included in both allowed_visit_reason_ids and excluded_visit_reason_ids, the net effect is that visit reason being excluded.

allowed	excluded	=> Result
null	null	all visit reasons allowed
[A,B]	null	only A & B are allowed
null	[A,B]	all visit reasons except A & B are allowed
[A,B]	[B,C]	only A is allowed (C is irrelevant)
[A,B]	[A,B]	No visit reasons allowed, unbookable timeslot

Example: ["pc_TAZW-r16U0B3pZeIutSI3L"]

timeslots[].patient_typestring(PatientType)

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

Enum"existing""new"

Example: "new"

curl -i -X PUT \
  'https://api-developer-sandbox.zocdoc.com/v1/providers/pr_abc123-def456_wxyz7890/calendar/timeslots?date=2024-10-16' \
  -H 'Content-Type: application/json' \
  -d '{
    "timeslots": [
      {
        "provider_id": "pr_abc123-def456_wxyz7890",
        "location_id": "lo_abc123-def456_wxyz7890",
        "start_time": "2024-10-16T09:30:00",
        "time_zone": "America/New_York",
        "allowed_visit_reason_ids": [
          "pc_TlZW-r06U0W3pCsIGtSI5B"
        ],
        "excluded_visit_reason_ids": [
          "pc_TAZW-r16U0B3pZeIutSI3L"
        ],
        "patient_type": "new"
      }
    ]
  }'