# API Documentation Version: 1.22 ## Servers Sandbox ``` https://api-developer-sandbox.zocdoc.com ``` Production ``` https://api-developer.zocdoc.com ``` ## Security ### ClientCredentialsFlow Machine to machine authentication (for use from client server to Zocdoc). Type: oauth2 ### AuthorizationCodeFlow Log in as a user. Client Secret is not necessary for this login flow. Type: oauth2 ## Download OpenAPI description [API Documentation](https://api-docs.zocdoc.com/_spec/apis/index.yaml) ## NPIs Endpoints to retrieve information about the developer's directory. ### Get active provider NPIs - [GET /v1/reference/npi](https://api-docs.zocdoc.com/apis/reference/getprovidernpis.md): Retrieves the list of active provider NPIs within the developer's Zocdoc directory. The NPIs retrieved here can be used to search for providers in the /v1/providers endpoint to facilitate availability, discovery, and booking. Developers can fetch the NPI list and cache in their system. The available NPIs do not change frequently. Pulling this data once a week and/or after known directory change events should be sufficient. ## Schedulable entities Endpoints to retrieve schedulable entities with availability information. ### Get schedulable entities - [GET /v1/schedulable_entities](https://api-docs.zocdoc.com/apis/schedulable-entities/getschedulableentities.md): (Sandbox Only) Get the list of schedulable entities within the developer's Zocdoc directory (provider-locations, etc.) with availability information. NPIs can be used to search for providers in the /v1/providers endpoint to facilitate availability, discovery, and booking. Schedulable entity ids can be used to find provider-locations in the /v1/provider_locations/{provider_location_id} endpoint to facilitate availability, discovery, and booking. Developers can fetch the schedulable entities list and cache in their system. The available schedulable entities do not change frequently. Pulling this data once a week and/or after known directory change events should be sufficient. However, you may use the parameter and the field to get the list of entities that have changed in the last 72 hours. ## Insurance Endpoints to retrieve insurance plans supported by Zocdoc. ### Get insurance plans - [GET /v1/insurance_plans](https://api-docs.zocdoc.com/apis/insurance-reference/getinsuranceplans.md): Get insurance plans ### Get insurance plan by id - [GET /v1/insurance_plans/{insurance_plan_id}](https://api-docs.zocdoc.com/apis/insurance-reference/getinsuranceplan.md): Get insurance plan by id. ## Providers Endpoints to retrieve providers within the developer's directory. ### Get providers by NPIs - [GET /v1/providers](https://api-docs.zocdoc.com/apis/providers/getproviders.md): Retrieves specific providers within the developer's directory by NPI search. This endpoint searches active providers that are listed on Zocdoc. It returns the provider's information (such as name, gender identity, specialty), location information and provider location IDs which can be used to look up availability and book appointments. Every developer has a designated provider directory jointly defined and onboarded in partnership with Zocdoc. The returned in the response can be used to retrieve availability in the endpoint /v1/provider_locations/availability. ## Provider locations Endpoints for retrieving and modifying provider location objects and their related reviews, insurance plans, and availability. ### Get provider locations - [GET /v1/provider_locations](https://api-docs.zocdoc.com/apis/provider-locations/getproviderlocations.md): 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 returned in the response can be used to retrieve availability in the endpoint /v1/provider_locations/availability. ### Get provider location by id - [GET /v1/provider_locations/{provider_location_id}](https://api-docs.zocdoc.com/apis/provider-locations/getproviderlocation.md): Get info about a provider location by provider_location_id ### Get availability for provider locations - [GET /v1/provider_locations/availability](https://api-docs.zocdoc.com/apis/provider-locations/getproviderlocationsavailability.md): 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. ### Get insurance mappings for provider location - [GET /v1/provider_locations/{provider_location_id}/insurance_mappings](https://api-docs.zocdoc.com/apis/provider-locations/getproviderlocationinsurancemappings.md): Get eligible insurance plans and insurance mappings for a provider location by provider_location_id ### Submit request to update mapped insurance plans - [POST /v1/provider_locations/{provider_location_id}/insurance_mappings](https://api-docs.zocdoc.com/apis/provider-locations/updateproviderlocationinsurancemappings.md): 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. ## Facilities Endpoints to retrieve facilities within the developer's directory. ### Get facilities - [GET /v1-beta/facilities](https://api-docs.zocdoc.com/apis/facilities/getfacilities.md): Get a set of facilities within the developer's network. ### Get facility by id - [GET /v1-beta/facilities/{facility_id}](https://api-docs.zocdoc.com/apis/facilities/getfacility.md): Get facility by facility id. ## Calendar integration timeslots Endpoints to manage timeslots for providers. ### Get timeslots for provider on date - [GET /v1/providers/{provider_id}/calendar/timeslots](https://api-docs.zocdoc.com/apis/calendar-integration-timeslots/getprovidercalendartimeslots.md): Get timeslots for a provider and date. ### Put provider calendar timeslots - [PUT /v1/providers/{provider_id}/calendar/timeslots](https://api-docs.zocdoc.com/apis/calendar-integration-timeslots/putprovidercalendartimeslots.md): This endpoint is used to set all slots for a given provider and date, replacing any existing slots. Sending an empty body will erase all slots for the specified date. : The timeslots are stored in an eventually consistent data store. This means there is a small possibility that a fetch might not include recently created slots if you fetch timeslots immediately after inserting them. : * The user must have access to the specified . : * : * Must match the specified in the endpoint parameter. * : * Must be a valid "local date-time" string in ISO 8601 format, e.g., . The seconds component is optional. * The date component must match the parameter. * : * Must be a valid IANA time zone ID (e.g., or ). ## Appointments Endpoints for booking, cancelling, and rescheduling appointments, including retrieving current appointment statuses and updated information. ### Create appointment - [POST /v1/appointments](https://api-docs.zocdoc.com/apis/appointments/createappointment.md): This endpoint is used for creating new appointments. Developers should gather the necessary information to pass in the request body as inputs for this endpoint. Only timeslots retrieved from the /v1/provider_locations/availability endpoint will be accepted. After an /appointments call is successfully processed, the system will return an appointment ID. The returned is used in the endpoint /v1/appointments/{appointment_id} to track the status of the appointment, and in the endpoint /v1/appointments/cancel to cancel an appointment. ### Get appointments - [GET /v1/appointments](https://api-docs.zocdoc.com/apis/appointments/getappointments.md): This endpoint retrieves the paginated list of appointment details and statuses for the given credential. By default, appointments will be returned in descending order of start time. A maximum of 1,000 total appointments will be returned via pagination; if more are expected, use filters and batch requests. If the request comes from a Zocdoc user credential, only appointments that user has created will be returned. If the request comes from a machine-to-machine credential, any appointments that were booked with that developer will be returned. ### Get appointment by id - [GET /v1/appointments/{appointment_id}](https://api-docs.zocdoc.com/apis/appointments/getappointment.md): This endpoint retrieves updated appointment details and the status of a single existing appointment. Developers must send a valid as input in the request body, and Zocdoc returns the appointment details and status for that appointment. See Appointment Status definitions. If the appointment was booked with a Zocdoc user credential, only that user will have access to view or modify the appointment. If the appointment was booked with a machine-to-machine credential, the appointment can be viewed and modified by any of the developer's machine-to-machine credentials. ### Get participants for appointment - [GET /v1/appointments/{appointment_id}/participants](https://api-docs.zocdoc.com/apis/appointments/getappointmentparticipants.md): This endpoint retrieves the participants of an appointment. Developers must provide a valid as a path parameter, and Zocdoc returns the participants of that appointment. ### Cancel appointment - [POST /v1/appointments/cancel](https://api-docs.zocdoc.com/apis/appointments/cancelappointment.md): This endpoint is used to request the cancellation of an appointment in a non-cancelled status. (Non-cancelled statuses include: pending_booking, booking_failed, confirmed, pending_reschedule, reschedule_failed and rescheduled) Developers must send a valid as input in the request body and may choose to pass a cancellation reason using the standardized field. The optional field should only be used when the cancellation reason type is 'other_patient_reason' or 'other_provider_reason' to provide additional context. If the appointment was booked with a Zocdoc user credential, only that user will have access to view or modify the appointment. If the appointment was booked with a machine-to-machine credential, the appointment can be viewed and modified by any of the developer's machine-to-machine credentials. ### Confirm appointment - [POST /v1/appointments/confirm](https://api-docs.zocdoc.com/apis/appointments/confirmappointment.md): This endpoint is used to confirm an appointment in pending booking status. Developers must send a valid as input in the request body. ### Reschedule appointment - [POST /v1/appointments/reschedule](https://api-docs.zocdoc.com/apis/appointments/rescheduleappointment.md): This endpoint is used to only modify the appointment time and request the reschedule of an appointment in pending_booking, confirmed, pending_reschedule, or rescheduled status. Developers must send a valid and a new start time as input in the request body. If the appointment was booked with a Zocdoc user credential, only that user will have access to view or modify the appointment. If the appointment was booked with a machine-to-machine credential, the appointment can be viewed and modified by any of the developer's machine-to-machine credentials. ### Create attachment for appointment - [POST /v1/appointments/{appointment_id}/attachments](https://api-docs.zocdoc.com/apis/appointments/uploadappointmentattachment.md): This endpoint is used to upload attachment documents related to the appointment for the provider to view. Only documents of type jpg, png, pdf, and docx are supported. Documents must be less than 10MB. You may not upload attachments to appointments in a failed state or over 7 days after the appointment. ### Update appointment status - [PUT /v1/appointments/update-status](https://api-docs.zocdoc.com/apis/appointments/updateappointmentstatus.md): Use this endpoint to update the status of an appointment to either 'arrived' or 'no_show'. - : Indicates the patient has arrived at the office. - : Indicates the patient did not show up for their scheduled appointment. Appointment start time should be in the past but no older than 2 days to be marked as no_show. ## Webhook Sandbox endpoints to mock webhook behavior ### Mock webhook request - [POST /v1/webhook/mock-request](https://api-docs.zocdoc.com/apis/webhook/mockwebhookrequest.md)