# 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 `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.

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

## Security:

  - `ClientCredentialsFlow` (unknown)
    oauth2 scopes: external.appointment.write

  - `AuthorizationCodeFlow` (unknown)
    oauth2 scopes: external.appointment.write

## 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.patient_id` (string)
    The Zocdoc ID of the patient.

  - `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. Use the [Get Insurance Plans](#operation/getInsurancePlans) endpoint to retrieve available plans.
    Example: ip_31820

  - `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.

  - `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. 100 character maximum limit.

## Response 200:

  - `200` (unknown)
    Successful

## Response 200 fields (application/json):

  - `request_id` (string, required)
    Unique request identifier for tracing

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

  - `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. 100 character maximum limit.

## Response 400:

  - `400` (unknown)
    Bad request

## Response 400 fields (application/json):

  - `request_id` (string, required)
    Unique request identifier for tracing

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

  - `errors` (array, required)

  - `errors.field` (string)

  - `errors.message` (string, required)

## Response 401:

  - `401` (unknown)
    Unauthorized

## Response 403:

  - `403` (unknown)
    Forbidden

## Response 404:

  - `404` (unknown)
    Provider location not found.

## Response 404 fields (application/json):

  - `request_id` (string, required)
    Unique request identifier for tracing

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

  - `errors` (array, required)

  - `errors.field` (string)

  - `errors.message` (string, required)

## Response 409:

  - `409` (unknown)
    Conflict

## Response 409 fields (application/json):

  - `request_id` (string, required)
    Unique request identifier for tracing

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

  - `errors` (array, required)

  - `errors.field` (string)

  - `errors.message` (string, required)