---
title: "Create appointment"
method: POST
path: "/v1/appointments"
tags: ["appointments"]
---

# Create appointment

`POST /v1/appointments`

## Request

- Base URL: `https://api-developer-sandbox.zocdoc.com`
- URL: `https://api-developer-sandbox.zocdoc.com/v1/appointments`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `https://auth.zocdoc.com/oauth/token` scopes: `external.appointment.write`
  - OAuth 2
    - Authorization code: `https://auth.zocdoc.com/authorize`
    - Token URL: `https://auth.zocdoc.com/oauth/token` scopes: `external.appointment.write`

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.

## Request body

- BookAppointmentRequestBody
  - `appointment_type` 'providers', required: The type of appointment.
  - `data` AppointmentData, required
    - `start_time` string, 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.
    - `visit_reason_id` string, required: The Zocdoc visit reason ID for the appointment. Must be accepted by the provider.
    - `provider_location_id` string, required: The Zocdoc provider-location ID for the appointment.
    - `patient` Patient, required
      - `patient_id` string: The Zocdoc ID of the patient.
      - `developer_patient_id` string: The patient identifier provided by 3P developer.
      - `first_name` string, required: The patient's first name.
      - `last_name` string, required: The patient's last name.
      - `date_of_birth` string, date, required: The patient's date of birth in the format, YYYY-MM-DD.
      - `sex_at_birth` 'male' | 'female', required: The patient's sex assigned at birth.
      - `phone_number` string, required: The patient's unformatted 10 digit phone number. The first and fourth digits cannot be a 0 or 1.
      - `email_address` string, required: The patient's email address.
      - `patient_address` PatientAddress, required
        - `address1` string, required: The patient's address, line 1.
        - `city` string, required: The patient's address, city.
        - `state` string, required: The patient's address, two letter state code.
        - `zip_code` string, required: The patient's address, 5 digit zip code.
        - `address2` string: The patient's address, line 2.
      - `insurance` PatientInsurance
        - `insurance_plan_id` string: The ID of the patient's insurance plan. Use the [Get Insurance Plans](#operation/getInsurancePlans) endpoint to retrieve available plans.
        - `insurance_group_number` string: The patients insurance group number.
        - `insurance_member_id` string: The patients insurance card member ID.
        - `is_self_pay` boolean: Indicates is a patient is self paying
      - `gender` Gender[]: none_apply and prefer_not_to_say must be used independently, all other gender identities can be used in combination with each other.
    - `patient_type` 'existing' | 'new', required: Whether or not the patient has been to the provider's practice.
    - `notes` string: Patient notes. 100 character maximum limit.

## Response `200`

Successful

- AppointmentResponse
  - `request_id` string, required: Unique request identifier for tracing
  - `data` AppointmentResponseData, required: Data that will be returned upon a sucessful booking request
    - `appointment_id` string, required: The Zocdoc ID of the appointment.
    - `appointment_status` 'pending_booking' | 'confirmed' | 'booking_failed' | 'cancelled' | 'no_show' | 'pending_reschedule' | 'rescheduled' | 'reschedule_failed', required: The status of the appointment. See [Appointment Status definitions](/guides/glossary).
    - `developer_patient_id` string: The patient identifier provided by 3P developer. Null if not provided.
    - `is_provider_resource` boolean, required: Whether the appointment will be performed by a professional under the supervision of the booked provider.
    - `location_phone_number` string: The appointment location's unformatted 10 digit phone number
    - `location_phone_extension` string: The appointment location's unformatted extension number, as digits
    - `waiting_room_path` string: Patient facing url that can be used to navigate to Zocdoc video service appointments
    - `confirmation_type` 'auto' | 'manual' | 'pending_evaluation', 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.
    - `visit_type` 'in_person' | 'zocdoc_video_service' | 'third_party_video_service', required: The appointment's [visit type](/guides/glossary)
    - `notes` string: Patient notes. 100 character maximum limit.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Provider location not found.
- `409`: Conflict

---

[API](https://skmtc.dev/zocdoc/apis/zocdoc-bundle-api.md) - [All operations](https://skmtc.dev/zocdoc/apis/zocdoc-bundle-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zocdoc/apis/zocdoc-bundle-api/revisions/965a6ca4ed12?raw)