# Create appointment

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.


Endpoint: POST /v1/appointments
Version: 1.22
Security: ClientCredentialsFlow, AuthorizationCodeFlow

## Request fields (application/json):

  - `appointment_type` (string, required)
    The type of appointment.
    Enum: "providers"

  - `data` (object, required)

  - `data.start_time` (string, 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_id` (string, required)
    The Zocdoc visit reason ID for the appointment. Must be accepted by the provider.
    Example: "pc_FRO-18leckytNKtruw5dLR"

  - `data.provider_location_id` (string, required)
    The Zocdoc provider-location ID for the appointment.
    Example: "pr_abc123-def456_wxyz7890|lo_abc123-def456_wxyz7890"

  - `data.patient` (object, required)

  - `data.patient.developer_patient_id` (string)
    The patient identifier provided by 3P developer.

  - `data.patient.first_name` (string, required)
    The patient's first name.

  - `data.patient.last_name` (string, required)
    The patient's last name.

  - `data.patient.date_of_birth` (string, required)
    The patient's date of birth in the format, YYYY-MM-DD.

  - `data.patient.sex_at_birth` (string, required)
    The patient's sex assigned at birth.
    Enum: "male", "female"

  - `data.patient.phone_number` (string, required)
    The patient's unformatted 10 digit phone number. The first and fourth digits cannot be a 0 or 1.
    Example: "9999999999"

  - `data.patient.email_address` (string, required)
    The patient's email address.
    Example: "test@example.com"

  - `data.patient.patient_address` (object, required)

  - `data.patient.patient_address.address1` (string, required)
    The patient's address, line 1.

  - `data.patient.patient_address.city` (string, required)
    The patient's address, city.

  - `data.patient.patient_address.state` (string, required)
    The patient's address, two letter state code.
    Example: "NY"

  - `data.patient.patient_address.zip_code` (string, required)
    The patient's address, 5 digit zip code.
    Example: 36925

  - `data.patient.patient_address.address2` (string)
    The patient's address, line 2.

  - `data.patient.insurance` (object)

  - `data.patient.insurance.insurance_plan_id` (string)
    The ID of the patient's insurance plan. See [Reference Data](/guides/reference-data) for options.
    Example: "ip_2224"

  - `data.patient.insurance.insurance_group_number` (string)
    The patients insurance group number.

  - `data.patient.insurance.insurance_member_id` (string)
    The patients insurance card member ID.

  - `data.patient.insurance.is_self_pay` (boolean)
    Indicates is a patient is self paying

  - `data.patient.gender` (array)
    none_apply and prefer_not_to_say must be used independently, all other gender identities can be used in combination with each other.
    Enum: "female_at_birth", "male_at_birth", "cisgender", "genderfluid", "genderqueer", "intersex", "non_binary", "transgender_man", "transgender_woman", "prefer_not_to_say", "none_apply"

  - `data.patient_type` (string, required)
    Whether or not the patient has been to the provider's practice.
    Enum: "existing", "new"

  - `data.notes` (string)
    Patient notes

## Response 200 fields (application/json):

  - `request_id` (string, required)

  - `data` (object, required)
    Data that will be returned upon a sucessful booking request

  - `data.appointment_id` (string, required)
    The Zocdoc ID of the appointment.

  - `data.appointment_status` (string, required)
    The status of the appointment. See [Appointment Status definitions](/guides/glossary).
    Enum: "pending_booking", "confirmed", "booking_failed", "cancelled", "no_show", "pending_reschedule", "rescheduled", "reschedule_failed"

  - `data.developer_patient_id` (string)

  - `data.is_provider_resource` (boolean, required)
    Whether the appointment will be performed by a professional under the supervision of the booked provider.

  - `data.location_phone_number` (string)
    The appointment location's unformatted 10 digit phone number
    Example: "9999999999"

  - `data.location_phone_extension` (string)
    The appointment location's unformatted extension number, as digits

  - `data.waiting_room_path` (string)
    Patient facing url that can be used to navigate to Zocdoc video service appointments

  - `data.confirmation_type` (string, 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_type` (string, required)
    The appointment's [visit type](/guides/glossary)
    Enum: "in_person", "zocdoc_video_service", "third_party_video_service"

  - `data.notes` (string)
    Patient notes

## Response 400 fields (application/json):

  - `request_id` (string, required)

  - `error_type` (string, required)
    Enum: "api_error", "invalid_request"

  - `errors` (array, required)

  - `errors.field` (string)

  - `errors.message` (string, required)