# API Documentation Version: 1.175 ## 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). Production: `https://auth.zocdoc.com/oauth/token` Sandbox: `https://auth-api-developer-sandbox.zocdoc.com/oauth/token` Type: oauth2 ### AuthorizationCodeFlow Log in as a user. Client Secret is not necessary for this login flow. Production: `https://auth.zocdoc.com` Sandbox: `https://auth-api-developer-sandbox.zocdoc.com` Type: oauth2 ## Download OpenAPI description [API Documentation](https://api-docs.zocdoc.com/_bundle/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): 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 recent_changes_72hrs parameter and the recent_change_summary 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 provider_location_id returned in the response can be used to retrieve availability in the endpoint /v1/provider_locations/availability. ### Get Provider Reviews - [GET /v1/providers/{provider_id}/reviews](https://api-docs.zocdoc.com/apis/providers/getproviderreviews.md): Get review summary for a provider by their Zocdoc provider ID. ## Provider locations Endpoints for retrieving and modifying provider location objects and their related 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 provider_location_id 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 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. ### 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 sets the complete list of available slots for a specific provider on a specific date. Each request must include the entire set of slots for that date. If a provider wishes to list times at multiple locations for a single date, each location must have its own timeslot object added to the array. A new request made for the same provider and date will overwrite the previous set of slots. If you send an empty array, all slots for that provider across all locations on that date will be deleted. Note: 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. Parameter Validations: * The user must have access to the specified provider_id. Validations for each timeslot in the request body: * slot.provider_id: * Must match the provider_id specified in the endpoint parameter. * slot.start_time: * Must be a valid "local date-time" string in ISO 8601 format, e.g., 2024-09-15T12:13:00. The seconds component is optional. * The date component must match the date parameter. * slot.time_zone: * Must be a valid IANA time zone ID (e.g., America/New_York or America/Denver). ## 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 appointment_id 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 appointment_id 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 appointment_id 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 appointment_id as input in the request body and may choose to pass a cancellation reason using the standardized cancellation_reason_type field. The optional cancellation_reason 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 appointment_id 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 appointment_id 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. You can upload more than one attachment with the same attachment_type for the same appointment_id if needed. The provider will be able to receive all uploaded attachments. 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'. - arrived: Indicates the patient has arrived at the office. - no_show: 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) ## Credentials Endpoints for managing API credentials. ### Rotate Credentials - [POST /v1/credentials/rotate](https://api-docs.zocdoc.com/apis/credentials/rotatecredentials.md): Rotate the client secret for the authenticated external API client.