Skip to content

API Documentation (1.22)

Download OpenAPI description
index.json
index.yaml
Languages
Servers
Sandbox

https://api-developer-sandbox.zocdoc.com/

Production

https://api-developer.zocdoc.com/

NPIs

Endpoints to retrieve information about the developer's directory.

Operations

Schedulable entities

Endpoints to retrieve schedulable entities with availability information.

Operations

Insurance

Endpoints to retrieve insurance plans supported by Zocdoc.

Operations

Providers

Endpoints to retrieve providers within the developer's directory.

Operations

Provider locations

Endpoints for retrieving and modifying provider location objects and their related reviews, insurance plans, and availability.

Operations

Get provider locations

Request

This endpoint accepts parameters such as zip code, specialty, visit reason and accepted insurance to return a filtered set of providers within the developer's directory. The response includes additional information about the provider location objects returned.

The provider_location_id returned in the response can be used to retrieve availability in the endpoint /v1/provider_locations/availability.

Security
ClientCredentialsFlow or AuthorizationCodeFlow
Query
zip_codestringrequired

A 5 digit zip code.

Example: zip_code=36925
specialty_idstring

The Zocdoc ID of the provider's specialty. See Reference Data for options. One of specialty_id or visit_reason_id is required. If visit_reason_id is not supplied, the default visit reason for the specialty will be used.

Example: specialty_id=sp_153
visit_reason_idstring

The Zocdoc ID for the visit reason. See Reference Data for options. One of specialty_id or visit_reason_id is required. If both visit_reason_id and specialty_id are supplied, the specialty must be the visit reason's corresponding specialty.

Example: visit_reason_id=pc_FRO-18leckytNKtruw5dLR
pageinteger[ 0 .. 10 ]

The zero indexed page of results.

Default 0
page_sizeinteger[ 1 .. 50 ]

The number of results to return per page.

Default 10
insurance_plan_idstring

The Zocdoc ID of the patient's insurance plan. See Reference Data for options.

Example: insurance_plan_id=ip_2224
visit_typestring(VisitType)

The type of patient visit with the provider. If not provided, the default value is set to in_person.

Default "in_person"
Enum"all""in_person""video_visit"
Example: visit_type=all
max_distance_to_patient_miinteger[ 1 .. 50 ]

The maximum distance in miles from the physical location to the search location (the center point of the given zip_code). Default is 50 miles.

Default 50
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>'

Responses

Succesful

Bodyapplication/json
request_idstringrequired
pageintegerrequired

The zero based index of the current page.

page_sizeintegerrequired

The size of the current page.

total_countintegerrequired

The total number of result items.

next_urlstringrequired

A link to the next page of results; null if this is the last page of results.

dataobject(ProviderSearchResult)required
data.​search_parametersobject(SearchParameters)required
data.​search_parameters.​specialty_idstringrequired

The Zocdoc ID of the specialty used to search with. If no specialty was provided by the developer, this will be the specialty associated with the visit reason ID that was provided.

Example: "sp_153"
data.​search_parameters.​visit_reason_idstringrequired

The Zocdoc ID of the visit reason used to search with. If no visit reason was provided by the developer, this will be the default visit reason for the specialty id that was provided.

Example: "pc_FRO-18leckytNKtruw5dLR"
data.​provider_locationsArray of objects(ProviderLocation)required
data.​provider_locations[].​provider_location_idstringrequired
Example: "pr_abc123-def456_wxyz7890|lo_abc123-def456_wxyz7890"
data.​provider_locations[].​provider_location_typestring(ProviderLocationType)required
Enum"in_person_provider""virtual_provider"
data.​provider_locations[].​accepts_patient_insurancestring(AcceptsPatientInsuranceType)required

Whether the provider location accepts the patient's insurance

Enum"accepted""not_accepted""insurance_not_specified"
data.​provider_locations[].​first_availability_date_in_provider_local_timestring(date)

The first date where provider has availability for new patients with any visit reason in provider's local time zone, formatted as YYYY-MM-DD and up to 90 days in the future.

data.​provider_locations[].​providerobject(BaseProvider)required
data.​provider_locations[].​provider.​npistring
data.​provider_locations[].​provider.​first_namestring
data.​provider_locations[].​provider.​last_namestring
data.​provider_locations[].​provider.​titlestring
data.​provider_locations[].​provider.​full_namestring
data.​provider_locations[].​provider.​gender_identitystring

Possible values include: Female, Male, Non-binary

data.​provider_locations[].​provider.​specialtiesArray of strings
data.​provider_locations[].​provider.​specialty_idsArray of strings
data.​provider_locations[].​provider.​default_visit_reason_idstring
data.​provider_locations[].​provider.​visit_reason_idsArray of strings
data.​provider_locations[].​provider.​statementstring
data.​provider_locations[].​provider.​provider_photo_urlstring

Url to a provider's photo.

Example: "https://d2uur722ua7fvv.cloudfront.net/ZeeFace_02.svg"
data.​provider_locations[].​provider.​languagesArray of strings

Languages spoken at the practice location, might be facilitated by translators on site. Download Languages csv.

Example: ["English","Spanish"]
data.​provider_locations[].​provider.​credentialsobject(ProviderCredentials)

Provider Credentials include education and certifications.

data.​provider_locations[].​locationobject(BaseLocationWithDistance)
data.​provider_locations[].​virtual_locationobject(BaseVirtualLocation)
data.​provider_locations[].​practiceobject(Practice)
data.​provider_locations[].​booking_requirementsobject(BookingRequirements)required

Criteria for booking appointments, defines requirements and mandatory fields specified by Zocdoc providers

data.​provider_locations[].​booking_requirements.​required_fieldsArray of stringsrequired
data.​provider_locations[].​booking_requirements.​accepts_booking_requests_fromArray of strings(BookingRequestInsuranceSource)required
Items Enum"in_network""out_of_network""self_pay"
Response
application/json
{
  "request_id": "string",
  "page": 0,
  "page_size": 0,
  "total_count": 0,
  "next_url": "string",
  "data": {
    "search_parameters": { … },
    "provider_locations": [ … ]
  }
}

Get provider location by id

Request

Get info about a provider location by provider_location_id

Security
ClientCredentialsFlow or AuthorizationCodeFlow
Path
provider_location_idstringrequired

The Zocdoc provider location id to get details for.

Example: pr_abc123-def456_wxyz7890|lo_abc123-def456_wxyz7890
Query
insurance_plan_idstring

The Zocdoc ID of the patient's insurance plan. See Reference Data for options.

Example: insurance_plan_id=ip_2224
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>'

Responses

Successful

Bodyapplication/json
request_idstringrequired
dataobject(ProviderLocation)
Response
application/json
{
  "request_id": "string",
  "data": {
    "provider_location_id": "pr_abc123-def456_wxyz7890|lo_abc123-def456_wxyz7890",
    "provider_location_type": "in_person_provider",
    "accepts_patient_insurance": "accepted",
    "first_availability_date_in_provider_local_time": "2019-08-24",
    "provider": { … },
    "location": { … },
    "virtual_location": { … },
    "practice": { … },
    "booking_requirements": { … }
  }
}

Get availability for provider locations

Request

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.

Security
ClientCredentialsFlow or AuthorizationCodeFlow
Query
provider_location_idsstringrequired

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.

Example: provider_location_ids=pr_abc123-def456_wxyz7890|lo_abc123-def456_wxyz7890,pr_ghi123-jkl456_mnop7890|lo_ghi123-jkl456_mnop7890
visit_reason_idstringrequired

The Zocdoc ID of the visit reason. See Reference Data for options.

Example: visit_reason_id=pc_FRO-18leckytNKtruw5dLR
patient_typestring(PatientType)required

New or existing to indicate if the patient is new to the practice or has been to the office before.

Enum"existing""new"
Example: patient_type=new
start_date_in_provider_local_timestring(date)

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_timestring(date)

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.

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

Responses

Successful

Bodyapplication/json
request_idstringrequired
dataArray of objects(Availability)

Response containing the availaibility information.

Response
application/json
{
  "request_id": "string",
  "data": [
    { … }
  ]
}

Get insurance mappings for provider location

Request

Get eligible insurance plans and insurance mappings for a provider location by provider_location_id

Security
ClientCredentialsFlow or AuthorizationCodeFlow
Path
provider_location_idstringrequired

The Zocdoc provider location id to get insurance plans for.

curl -i -X GET \
  'https://api-developer-sandbox.zocdoc.com/v1/provider_locations/{provider_location_id}/insurance_mappings' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/json
request_idstringrequired
dataobject(InsuranceMappingData)required
data.​insurance_plan_mappingsArray of objects(InsurancePlanMapping)required

List of insurance plans that are mapped

data.​insurance_plan_mappings[].​insurance_plan_idstringrequired
data.​eligible_insurancesArray of objects(EligibleInsurance)required

List of insurance networks and their plans that can be mapped

data.​eligible_insurances[].​insurance_carrier_idstringrequired
data.​eligible_insurances[].​insurance_carrier_networksArray of objects(InsuranceCarrierNetwork)required
data.​eligible_insurances[].​insurance_carrier_networks[].​program_typestringrequired
data.​eligible_insurances[].​insurance_carrier_networks[].​network_typestringrequired
data.​eligible_insurances[].​insurance_carrier_networks[].​insurance_plan_idsArray of stringsrequired
Response
application/json
{
  "request_id": "string",
  "data": {
    "insurance_plan_mappings": [ … ],
    "eligible_insurances": [ … ]
  }
}

Submit request to update mapped insurance plans

Request

Submits a request to update mapped insurance plans. This is an asynchronous operation and the response indicates the request was accepted for processing, not that the update is complete.

Security
ClientCredentialsFlow
Path
provider_location_idstringrequired

The Zocdoc provider location id to get insurance plans for.

Bodyapplication/jsonrequired
insurance_plan_idsArray of stringsrequired

List of insurance plan ids

operationstring(InsuranceMappingUpdateOperation)required
Enum"Add""Remove""Replace"
curl -i -X POST \
  'https://api-developer-sandbox.zocdoc.com/v1/provider_locations/{provider_location_id}/insurance_mappings' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "insurance_plan_ids": [
      "string"
    ],
    "operation": "Add"
  }'

Responses

Accepted

Bodyapplication/json
request_idstringrequired
Response
application/json
{
  "request_id": "string"
}

Facilities

Endpoints to retrieve facilities within the developer's directory.

Operations

Calendar integration timeslots

Endpoints to manage timeslots for providers.

Operations

Appointments

Endpoints for booking, cancelling, and rescheduling appointments, including retrieving current appointment statuses and updated information.

Operations

Webhook

Sandbox endpoints to mock webhook behavior

Operations
Copyright © Zocdoc Inc. All rights reserved.