# Find Provider Availability and Book Appointments Before using this guide you will need a developer account and an access token. You can contact us about creating a developer account [here](https://developer.zocdoc.com/?utm_medium=organicpro&utm_routing=API_Sender#api-form). To get an access token, review the [authentication and access tokens](/guides/authentication) guide. ## 1. Get NPIs First you need to retrieve the list of active provider NPIs within your Zocdoc directory. A Zocdoc directory is a developer-managed list of Zocdoc providers. Each developer account has at least one directory, and multiple directories can be created if needed to support your specific API use case. The primary purpose of a directory is to define which providers are available for booking through your application. You can also use directories to explore the Zocdoc marketplace and identify providers you may want to include in your bookable directory. ## 2. Get provider information There are three ways to retrieve provider-specific information: details summary strong Search by NPI NPIs retrieved in the previous step can be used to fetch detailed provider information, including name, gender identity, spoken languages, specialties, visit reasons, and affiliated locations. Up to 50 NPIs can be queried in a single request. details summary strong Search by ZIP and specialty or visit reason If you don’t have NPIs, you can search by ZIP code and specialty or visit reason to find providers. This is beneficial when looking by distance or specifc reason. details summary strong Search by provider location You can also retrieve provider information using specific `provider_location_id`s. This is useful for patients who want to see a specific doctor at a specific location. ## 3. Get availability Using a specific `provider_location_id`, `visit_reason_id`, and `patient_type`, you can retrieve the provider's availability. `start_date_in_provider_local_time` defaults to current date in US Eastern Time. `YYYY-MM-DD` format. `end_date_in_provider_local_time` defaults to 7 days after the current date. Must be 30 days or less after the start date. You can request availability up to a maximum of 150 days into the future. ## 4. Book an appointment Using an available `start_time` you can create an appointment for the patient. This will return an `appointment_id` which can be used to confirm, cancel, or reschedule the appointment. ```json { "$ref": "#/components/schemas/BookAppointmentRequestBody", "components": { "schemas": { "AppointmentType": { "type": "string", "enum": [ "providers" ], "description": "The type of appointment." }, "PatientSex": { "type": "string", "description": "The patient's sex assigned at birth.", "enum": [ "male", "female" ] }, "PatientAddress": { "required": [ "address1", "city", "state", "zip_code" ], "type": "object", "properties": { "address1": { "type": "string", "description": "The patient's address, line 1." }, "city": { "type": "string", "description": "The patient's address, city." }, "state": { "type": "string", "description": "The patient's address, two letter state code.", "example": "NY" }, "zip_code": { "type": "string", "description": "The patient's address, 5 digit zip code.", "example": 36925 }, "address2": { "type": "string", "description": "The patient's address, line 2." } } }, "PatientInsurance": { "type": "object", "properties": { "insurance_plan_id": { "type": "string", "description": "The ID of the patient's insurance plan. Use the [Get Insurance Plans](#operation/getInsurancePlans) endpoint to retrieve available plans.", "example": "ip_2224" }, "insurance_group_number": { "type": "string", "description": "The patients insurance group number." }, "insurance_member_id": { "type": "string", "description": "The patients insurance card member ID." }, "is_self_pay": { "type": "boolean", "description": "Indicates is a patient is self paying" } } }, "Gender": { "type": "string", "description": "Patient's gender values\n * Female at birth - Assigned female at birth\n * Male at birth - Assigned male at birth\n * Cisgender - A person whose current gender corresponds to the sex they were assigned at birth\n * Genderfluid - A person who does not identify with a fixed gender\n * Genderqueer - A person who does not follow binary gender norms\n * Intersex - A person born with traits, including genital anatomy, reproductive organs, hormone function, and/or chromosome patterns that may not fit the typical definition of male or female\n * Non-binary - Umbrella term for a person whose gender identity lies outside the gender binary\n * Transgender man - A person whose gender is male and whose sex assigned at birth was female\n * Transgender woman - A person whose gender is female and whose sex assigned at birth was male\n", "enum": [ "female_at_birth", "male_at_birth", "cisgender", "genderfluid", "genderqueer", "intersex", "non_binary", "transgender_man", "transgender_woman", "prefer_not_to_say", "none_apply" ] }, "Patient": { "required": [ "first_name", "last_name", "date_of_birth", "sex_at_birth", "phone_number", "email_address", "patient_address" ], "type": "object", "properties": { "patient_id": { "type": "string", "description": "The Zocdoc ID of the patient." }, "developer_patient_id": { "type": "string", "description": "The patient identifier provided by 3P developer." }, "first_name": { "type": "string", "description": "The patient's first name." }, "last_name": { "type": "string", "description": "The patient's last name." }, "date_of_birth": { "type": "string", "format": "date", "description": "The patient's date of birth in the format, YYYY-MM-DD." }, "sex_at_birth": { "$ref": "#/components/schemas/PatientSex" }, "phone_number": { "type": "string", "description": "The patient's unformatted 10 digit phone number. The first and fourth digits cannot be a 0 or 1.", "example": "9999999999" }, "email_address": { "type": "string", "description": "The patient's email address.", "example": "test@example.com" }, "patient_address": { "$ref": "#/components/schemas/PatientAddress" }, "insurance": { "$ref": "#/components/schemas/PatientInsurance" }, "gender": { "type": "array", "items": { "$ref": "#/components/schemas/Gender" }, "description": "none_apply and prefer_not_to_say must be used independently, all other gender identities can be used in combination with each other." } } }, "PatientType": { "type": "string", "description": "Whether or not the patient has been to the provider's practice.", "enum": [ "existing", "new" ], "example": "new" }, "AppointmentData": { "required": [ "start_time", "visit_reason_id", "provider_location_id", "patient", "patient_type" ], "type": "object", "properties": { "start_time": { "type": "string", "format": "date-time", "description": "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" }, "visit_reason_id": { "type": "string", "description": "The Zocdoc visit reason ID for the appointment. Must be accepted by the provider.", "example": "pc_FRO-18leckytNKtruw5dLR" }, "provider_location_id": { "type": "string", "description": "The Zocdoc provider-location ID for the appointment.", "example": "pr_abc123-def456_wxyz7890|lo_abc123-def456_wxyz7890" }, "patient": { "$ref": "#/components/schemas/Patient" }, "patient_type": { "$ref": "#/components/schemas/PatientType" }, "notes": { "type": "string", "description": "Patient notes" } } }, "BookAppointmentRequestBody": { "required": [ "appointment_type", "data" ], "type": "object", "properties": { "appointment_type": { "$ref": "#/components/schemas/AppointmentType" }, "data": { "$ref": "#/components/schemas/AppointmentData" } } } } } } ```