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

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

Create appointment

Request

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.

Security
ClientCredentialsFlow or AuthorizationCodeFlow
Bodyapplication/jsonrequired
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"
    }
  }'

Responses

Successful

Bodyapplication/json
request_idstringrequired
dataobject(AppointmentResponseData)required

Data that will be returned upon a sucessful booking request

data.​appointment_idstringrequired

The Zocdoc ID of the appointment.

data.​appointment_statusstring(AppointmentStatus)required

The status of the appointment. See Appointment Status definitions.

Enum"pending_booking""confirmed""booking_failed""cancelled""no_show""pending_reschedule""rescheduled""reschedule_failed"
data.​developer_patient_idstring
data.​is_provider_resourcebooleanrequired

Whether the appointment will be performed by a professional under the supervision of the booked provider.

data.​location_phone_numberstring

The appointment location's unformatted 10 digit phone number

Example: "9999999999"
data.​location_phone_extensionstring

The appointment location's unformatted extension number, as digits

data.​waiting_room_pathstring

Patient facing url that can be used to navigate to Zocdoc video service appointments

data.​confirmation_typestring(AppointmentConfirmationType)required

Specifies how the appointment confirmation will be handled.

  • auto: means the system will automatically confirm.
  • manual: means confirmation requires user action.
  • pending_evaluation: indicates that the confirmation approach is pending evaluation.
Enum"auto""manual""pending_evaluation"
data.​visit_typestring(AppointmentVisitType)required

The appointment's visit type

Enum"in_person""zocdoc_video_service""third_party_video_service"
data.​notesstring

Patient notes

Response
application/json
{
  "request_id": "string",
  "data": {
    "appointment_id": "string",
    "appointment_status": "pending_booking",
    "developer_patient_id": "string",
    "is_provider_resource": true,
    "location_phone_number": "9999999999",
    "location_phone_extension": "string",
    "waiting_room_path": "string",
    "confirmation_type": "auto",
    "visit_type": "in_person",
    "notes": "string"
  }
}

Get appointments

Request

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.

Security
ClientCredentialsFlow or AuthorizationCodeFlow
Query
pageinteger[ 0 .. 10 ]

The zero indexed page of results. A mimimum value of 0 and a maximum of 10 will be accepted.

Default 0
page_sizeinteger[ 1 .. 100 ]

The number of results to return per page. A mimimum value of 1 and a maximum of 100 will be accepted.

Default 10
statusesstring

A comma-delimited list of Zocodc appointment statuses to filter appointments by.

Example: statuses=pending_booking,confirmed
developer_patient_idstring

The patient identifier provided by 3P developer to filter appointments by.

sort_bystring(AppointmentSortByType)

The field to sort appointments by. Default is start_time.

Enum"start_time_utc""created_time_utc""last_modified_time_utc"
sort_directionstring(AppointmentSortDirectionType)

The direction to sort appointments by. Default is descending.

Enum"ascending""descending"
provider_idsstring

The comma separated values of provider ids to filter appointments by

Example: provider_ids=pr_abc123-def456_wxyz7890,pr_ghi123-jkl456_mnop7890
location_idsstring

The comma separated values of location ids to filter appointments by

Example: location_ids=lo_abc123-def456_wxyz7890,lo_ghi123-jkl456_mnop7890
practice_idsstring

The comma separated values of practice ids to filter appointments by

Example: practice_ids=pt_abc123-def456_wxyz7890,pt_ghi123-jkl456_mnop7890
start_time_utc_minstring

The minimum UTC start time of the appointments to fetch. Exclude appointments that start before this time.

Example: start_time_utc_min=2024-01-01T00:00:00Z
start_time_utc_maxstring

The maximum UTC start time of the appointments to fetch. Exclude appointments that start after this time.

Example: start_time_utc_max=2024-01-01T00:00:00Z
created_time_utc_minstring

The minimum UTC created time of the appointments to fetch. Exclude appointments that were created before this time.

Example: created_time_utc_min=2024-01-01T00:00:00Z
created_time_utc_maxstring

The maximum UTC created time of the appointments to fetch. Exclude appointments that were created after this time.

Example: created_time_utc_max=2024-01-01T00:00:00Z
last_modified_time_utc_minstring

The minimum UTC last modified time of the appointments to fetch. Exclude appointments that were last modified before this time.

Example: last_modified_time_utc_min=2024-01-01T00:00:00Z
last_modified_time_utc_maxstring

The maximum UTC last modified time of the appointments to fetch. Exclude appointments that were last modified after this time.

Example: last_modified_time_utc_max=2024-01-01T00:00:00Z
curl -i -X GET \
  'https://api-developer-sandbox.zocdoc.com/v1/appointments?page=0&page_size=10&statuses=pending_booking%2Cconfirmed&developer_patient_id=string&sort_by=start_time_utc&sort_direction=ascending&provider_ids=pr_abc123-def456_wxyz7890%2Cpr_ghi123-jkl456_mnop7890&location_ids=lo_abc123-def456_wxyz7890%2Clo_ghi123-jkl456_mnop7890&practice_ids=pt_abc123-def456_wxyz7890%2Cpt_ghi123-jkl456_mnop7890&start_time_utc_min=2024-01-01T00%3A00%3A00Z&start_time_utc_max=2024-01-01T00%3A00%3A00Z&created_time_utc_min=2024-01-01T00%3A00%3A00Z&created_time_utc_max=2024-01-01T00%3A00%3A00Z&last_modified_time_utc_min=2024-01-01T00%3A00%3A00Z&last_modified_time_utc_max=2024-01-01T00%3A00%3A00Z' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful

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.

dataArray of objects(AppointmentStatusResponseData)required
data[].​appointment_idstringrequired

The Zocdoc ID of the appointment.

data[].​appointment_statusstring(AppointmentStatus)required

The status of the appointment. See Appointment Status definitions.

Enum"pending_booking""confirmed""booking_failed""cancelled""no_show""pending_reschedule""rescheduled""reschedule_failed"
data[].​developer_patient_idstring
data[].​is_provider_resourcebooleanrequired

Whether the appointment will be performed by a professional under the supervision of the booked provider.

data[].​location_phone_numberstring

The appointment location's unformatted 10 digit phone number

Example: "9999999999"
data[].​location_phone_extensionstring

The appointment location's unformatted extension number, as digits

data[].​waiting_room_pathstring

Patient facing url that can be used to navigate to Zocdoc video service appointments

data[].​confirmation_typestring(AppointmentConfirmationType)required

Specifies how the appointment confirmation will be handled.

  • auto: means the system will automatically confirm.
  • manual: means confirmation requires user action.
  • pending_evaluation: indicates that the confirmation approach is pending evaluation.
Enum"auto""manual""pending_evaluation"
data[].​start_timestring(date-time)required

Date & time of the appointment

Example: "2022-04-27T09:00:00-04:00"
data[].​created_time_utcstring

UTC date & time of the appointment creation

Example: "2024-01-01T09:30:00Z"
data[].​last_modified_time_utcstring

UTC date & time of the appointment last modification

Example: "2024-01-01T09:30:00Z"
data[].​provider_location_idstringrequired
data[].​practice_idstring

The Zocdoc id of the practice

data[].​visit_reason_idstringrequired
data[].​visit_typestring(AppointmentVisitType)

The appointment's visit type

Enum"in_person""zocdoc_video_service""third_party_video_service"
data[].​patient_typestring(PatientType)

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

Enum"existing""new"
Example: "new"
data[].​notesstring

Patient notes

data[].​cancellation_reasonstring<= 50 characters

Optional free text description for the appointment cancellation. Only use this field when cancellation_reason_type is set to 'other_patient_reason' or 'other_provider_reason'.

data[].​cancellation_reason_typestring(CancellationReasonType)

Enum field describing why the appointment was cancelled. This field is optional but recommended when known for metrics purposes. If the cancellation reason does not match any predefined enum values, use 'other_patient_reason' or 'other_provider_reason' and provide a free text explanation in the cancellation_reason field.

Enum"patient_no_longer_needs_appointment""patient_no_longer_available""other_patient_reason""missing_needed_patient_information""payment_or_insurance_issue""patient_or_visit_type_not_accepted""provider_not_available""rescheduling_patient""other_provider_reason"
Response
application/json
{
  "request_id": "string",
  "page": 0,
  "page_size": 0,
  "total_count": 0,
  "next_url": "string",
  "data": [
    { … }
  ]
}

Get appointment by id

Request

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.

Security
ClientCredentialsFlow or AuthorizationCodeFlow
Path
appointment_idstringrequired

The Zocdoc ID for the appointment.

Example: d04b049a-41b1-4aba-9268-d8973cf72cdd
curl -i -X GET \
  https://api-developer-sandbox.zocdoc.com/v1/appointments/d04b049a-41b1-4aba-9268-d8973cf72cdd \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Successful

Bodyapplication/json
request_idstringrequired
dataobject(AppointmentStatusResponseData)required

Data that will be returned upon a sucessful booking request

data.​appointment_idstringrequired

The Zocdoc ID of the appointment.

data.​appointment_statusstring(AppointmentStatus)required

The status of the appointment. See Appointment Status definitions.

Enum"pending_booking""confirmed""booking_failed""cancelled""no_show""pending_reschedule""rescheduled""reschedule_failed"
data.​developer_patient_idstring
data.​is_provider_resourcebooleanrequired

Whether the appointment will be performed by a professional under the supervision of the booked provider.

data.​location_phone_numberstring

The appointment location's unformatted 10 digit phone number

Example: "9999999999"
data.​location_phone_extensionstring

The appointment location's unformatted extension number, as digits

data.​waiting_room_pathstring

Patient facing url that can be used to navigate to Zocdoc video service appointments

data.​confirmation_typestring(AppointmentConfirmationType)required

Specifies how the appointment confirmation will be handled.

  • auto: means the system will automatically confirm.
  • manual: means confirmation requires user action.
  • pending_evaluation: indicates that the confirmation approach is pending evaluation.
Enum"auto""manual""pending_evaluation"
data.​start_timestring(date-time)required

Date & time of the appointment

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

UTC date & time of the appointment creation

Example: "2024-01-01T09:30:00Z"
data.​last_modified_time_utcstring

UTC date & time of the appointment last modification

Example: "2024-01-01T09:30:00Z"
data.​provider_location_idstringrequired
data.​practice_idstring

The Zocdoc id of the practice

data.​visit_reason_idstringrequired
data.​visit_typestring(AppointmentVisitType)

The appointment's visit type

Enum"in_person""zocdoc_video_service""third_party_video_service"
data.​patient_typestring(PatientType)

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

Enum"existing""new"
Example: "new"
data.​notesstring

Patient notes

data.​cancellation_reasonstring<= 50 characters

Optional free text description for the appointment cancellation. Only use this field when cancellation_reason_type is set to 'other_patient_reason' or 'other_provider_reason'.

data.​cancellation_reason_typestring(CancellationReasonType)

Enum field describing why the appointment was cancelled. This field is optional but recommended when known for metrics purposes. If the cancellation reason does not match any predefined enum values, use 'other_patient_reason' or 'other_provider_reason' and provide a free text explanation in the cancellation_reason field.

Enum"patient_no_longer_needs_appointment""patient_no_longer_available""other_patient_reason""missing_needed_patient_information""payment_or_insurance_issue""patient_or_visit_type_not_accepted""provider_not_available""rescheduling_patient""other_provider_reason"
Response
application/json
{
  "request_id": "string",
  "data": {
    "appointment_id": "string",
    "appointment_status": "pending_booking",
    "developer_patient_id": "string",
    "is_provider_resource": true,
    "location_phone_number": "9999999999",
    "location_phone_extension": "string",
    "waiting_room_path": "string",
    "confirmation_type": "auto",
    "start_time": "2022-04-27T09:00:00-04:00",
    "created_time_utc": "2024-01-01T09:30:00Z",
    "last_modified_time_utc": "2024-01-01T09:30:00Z",
    "provider_location_id": "string",
    "practice_id": "string",
    "visit_reason_id": "string",
    "visit_type": "in_person",
    "patient_type": "new",
    "notes": "string",
    "cancellation_reason": "string",
    "cancellation_reason_type": "patient_no_longer_needs_appointment"
  }
}

Get participants for appointment

Request

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.

Security
ClientCredentialsFlow or AuthorizationCodeFlow
Path
appointment_idstringrequired

The Zocdoc id of the appointment

Example: d04b049a-41b1-4aba-9268-d8973cf72cdd
curl -i -X GET \
  https://api-developer-sandbox.zocdoc.com/v1/appointments/d04b049a-41b1-4aba-9268-d8973cf72cdd/participants \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/json
request_idstringrequired
dataobject(AppointmentParticipantsResponseData)required
data.​patientobject(AppointmentParticipantPatient)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.​uploaded_attachmentsArray of objects(UploadedAttachment)required

Documents and files that have been uploaded by the patient for this appointment, such as insurance cards, ID cards, or intake forms.

data.​patient.​uploaded_attachments[].​attachment_typestring(UploadedAttachmentType)required

Types of attachments that patients have uploaded and are returned in participant data.

Enum"insurance_card_medical""insurance_card_dental""insurance_card_vision""insurance_card_secondary""id_card""intake_form""other"
data.​patient.​uploaded_attachments[].​attachment_urlstringrequired

A full URL to download the attachment pointing to one of auxiliary endpoints in the same API. To access the url the same authentication must be used as the one used to make the request to /participants endpoint.

data.​patient.​uploaded_attachments[].​sidestring(DocumentSide)

Indicates whether the document image is of the front or back side. This field is typically used for documents like insurance cards or ID cards that have information on both sides.

Enum"front""back"
data.​patient.​is_booked_by_another_patientbooleanrequired

Indicates whether this patient's appointment was booked by another patient (e.g., a parent booking for their child or someone booking for a dependent)

data.​provider_idstringrequired

The Zocdoc id of the provider

data.​location_idstringrequired

The Zocdoc id of the location

Response
application/json
{
  "request_id": "string",
  "data": {
    "patient": { … },
    "provider_id": "string",
    "location_id": "string"
  }
}

Cancel appointment

Request

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.

Security
ClientCredentialsFlow or AuthorizationCodeFlow
Bodyapplication/jsonrequired
appointment_idstringrequired

The Zocdoc ID of the appointment.

Example: "d04b049a-41b1-4aba-9268-d8973cf72cdd"
cancellation_reasonstring<= 50 characters

Optional free text description for the appointment cancellation. Only use this field when cancellation_reason_type is set to 'other_patient_reason' or 'other_provider_reason'.

cancellation_reason_typestring(CancellationReasonType)

Enum field describing why the appointment was cancelled. This field is optional but recommended when known for metrics purposes. If the cancellation reason does not match any predefined enum values, use 'other_patient_reason' or 'other_provider_reason' and provide a free text explanation in the cancellation_reason field.

Enum"patient_no_longer_needs_appointment""patient_no_longer_available""other_patient_reason""missing_needed_patient_information""payment_or_insurance_issue""patient_or_visit_type_not_accepted""provider_not_available""rescheduling_patient""other_provider_reason"
curl -i -X POST \
  https://api-developer-sandbox.zocdoc.com/v1/appointments/cancel \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "appointment_id": "d04b049a-41b1-4aba-9268-d8973cf72cdd",
    "cancellation_reason": "string",
    "cancellation_reason_type": "patient_no_longer_needs_appointment"
  }'

Responses

Successful

Bodyapplication/json
request_idstringrequired
dataobject(AppointmentBaseResponseData)required

Data that will be returned upon a sucessful booking request

data.​appointment_idstringrequired

The Zocdoc ID of the appointment.

data.​appointment_statusstring(AppointmentStatus)required

The status of the appointment. See Appointment Status definitions.

Enum"pending_booking""confirmed""booking_failed""cancelled""no_show""pending_reschedule""rescheduled""reschedule_failed"
data.​developer_patient_idstring
Response
application/json
{
  "request_id": "string",
  "data": {
    "appointment_id": "string",
    "appointment_status": "pending_booking",
    "developer_patient_id": "string"
  }
}

Confirm appointment

Request

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.

Security
ClientCredentialsFlow or AuthorizationCodeFlow
Bodyapplication/jsonrequired
appointment_idstring
Example: "d04b049a-41b1-4aba-9268-d8973cf72cdd"
curl -i -X POST \
  https://api-developer-sandbox.zocdoc.com/v1/appointments/confirm \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "appointment_id": "d04b049a-41b1-4aba-9268-d8973cf72cdd"
  }'

Responses

Success

Bodyapplication/json
request_idstringrequired
dataobject(AppointmentBaseResponseData)required

Data that will be returned upon a sucessful booking request

data.​appointment_idstringrequired

The Zocdoc ID of the appointment.

data.​appointment_statusstring(AppointmentStatus)required

The status of the appointment. See Appointment Status definitions.

Enum"pending_booking""confirmed""booking_failed""cancelled""no_show""pending_reschedule""rescheduled""reschedule_failed"
data.​developer_patient_idstring
Response
application/json
{
  "request_id": "string",
  "data": {
    "appointment_id": "string",
    "appointment_status": "pending_booking",
    "developer_patient_id": "string"
  }
}

Reschedule appointment

Request

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.

Security
ClientCredentialsFlow or AuthorizationCodeFlow
Bodyapplication/jsonrequired
appointment_idstringrequired

The Zocdoc id of the appointment

Example: "63f995c2-49c4-40c8-a93a-140fb32e913b"
start_timestring(date-time)required

Date & time of the appointment in ISO-8601 format with a timezone offset

Example: "2022-04-27T09:00:00-04:00"
curl -i -X POST \
  https://api-developer-sandbox.zocdoc.com/v1/appointments/reschedule \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "appointment_id": "63f995c2-49c4-40c8-a93a-140fb32e913b",
    "start_time": "2022-04-27T09:00:00-04:00"
  }'

Responses

Successful

Bodyapplication/json
request_idstringrequired
dataobject(AppointmentResponseData)required

Data that will be returned upon a sucessful booking request

data.​appointment_idstringrequired

The Zocdoc ID of the appointment.

data.​appointment_statusstring(AppointmentStatus)required

The status of the appointment. See Appointment Status definitions.

Enum"pending_booking""confirmed""booking_failed""cancelled""no_show""pending_reschedule""rescheduled""reschedule_failed"
data.​developer_patient_idstring
data.​is_provider_resourcebooleanrequired

Whether the appointment will be performed by a professional under the supervision of the booked provider.

data.​location_phone_numberstring

The appointment location's unformatted 10 digit phone number

Example: "9999999999"
data.​location_phone_extensionstring

The appointment location's unformatted extension number, as digits

data.​waiting_room_pathstring

Patient facing url that can be used to navigate to Zocdoc video service appointments

data.​confirmation_typestring(AppointmentConfirmationType)required

Specifies how the appointment confirmation will be handled.

  • auto: means the system will automatically confirm.
  • manual: means confirmation requires user action.
  • pending_evaluation: indicates that the confirmation approach is pending evaluation.
Enum"auto""manual""pending_evaluation"
data.​visit_typestring(AppointmentVisitType)required

The appointment's visit type

Enum"in_person""zocdoc_video_service""third_party_video_service"
data.​notesstring

Patient notes

Response
application/json
{
  "request_id": "string",
  "data": {
    "appointment_id": "string",
    "appointment_status": "pending_booking",
    "developer_patient_id": "string",
    "is_provider_resource": true,
    "location_phone_number": "9999999999",
    "location_phone_extension": "string",
    "waiting_room_path": "string",
    "confirmation_type": "auto",
    "visit_type": "in_person",
    "notes": "string"
  }
}

Create attachment for appointment

Request

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.

Security
ClientCredentialsFlow or AuthorizationCodeFlow
Path
appointment_idstringrequired
Bodymultipart/form-datarequired
attachmentstring(binary)required
attachment_typestring(AttachmentType)required
Enum"community_care_packet""pcp_patient_referral"
curl -i -X POST \
  'https://api-developer-sandbox.zocdoc.com/v1/appointments/{appointment_id}/attachments' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F attachment=string \
  -F attachment_type=community_care_packet

Responses

Successfully uploaded attachment

Bodyapplication/json
request_idstringrequired
dataobject(UploadAppointmentAttachmentResponseData)required
data.​appointment_idstringrequired
data.​attachmentsArray of objects(UploadedAppointmentAttachment)required
data.​attachments[].​attachment_typestring(AttachmentType)required
Enum"community_care_packet""pcp_patient_referral"
Response
application/json
{
  "request_id": "string",
  "data": {
    "appointment_id": "string",
    "attachments": [ … ]
  }
}

Update appointment status

Request

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.
Security
ClientCredentialsFlow or AuthorizationCodeFlow
Bodyapplication/jsonrequired
appointment_idstringrequired

The Zocdoc ID of the appointment.

Example: "d04b049a-41b1-4aba-9268-d8973cf72cdd"
appointment_statusstring(AppointmentStatusToSet)required

New status to set for the appointment. Accepted values:

  • arrived: Patient has arrived at the office.
  • no_show: Patient did not show up for their appointment.
Enum"arrived""no_show"
curl -i -X PUT \
  https://api-developer-sandbox.zocdoc.com/v1/appointments/update-status \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "appointment_id": "d04b049a-41b1-4aba-9268-d8973cf72cdd",
    "appointment_status": "arrived"
  }'

Responses

Successful status update

Bodyapplication/json
request_idstringrequired
dataobject(AppointmentBaseResponseData)required

Data that will be returned upon a sucessful booking request

data.​appointment_idstringrequired

The Zocdoc ID of the appointment.

data.​appointment_statusstring(AppointmentStatus)required

The status of the appointment. See Appointment Status definitions.

Enum"pending_booking""confirmed""booking_failed""cancelled""no_show""pending_reschedule""rescheduled""reschedule_failed"
data.​developer_patient_idstring
Response
application/json
{
  "request_id": "string",
  "data": {
    "appointment_id": "string",
    "appointment_status": "pending_booking",
    "developer_patient_id": "string"
  }
}

Webhook

Sandbox endpoints to mock webhook behavior

Operations
Copyright © Zocdoc Inc. All rights reserved.