openapi: 3.0.0
info:
  version: '1.176'
  title: API Documentation appointments providers API
  description: Endpoints for booking, cancelling, and rescheduling appointments, including retrieving current appointment statuses and updated information.
servers:
- url: https://api-developer-sandbox.zocdoc.com
  description: Sandbox
- url: https://api-developer.zocdoc.com
  description: Production
tags:
- name: providers
  description: Endpoints to retrieve providers within the developer's directory.
  x-displayName: Providers
paths:
  /v1/providers:
    get:
      tags:
      - providers
      summary: Get providers by NPIs
      description: 'Retrieves specific providers within the developer''s directory by NPI search. This endpoint searches active providers that are listed on Zocdoc. It returns the provider''s information (such as name, gender identity, specialty), location information and provider location IDs which can be used to look up availability and book appointments. Every developer has a designated provider directory jointly defined and onboarded in partnership with Zocdoc.


        The `provider_location_id` returned in the response can be used to retrieve availability in the endpoint /v1/provider_locations/availability.

        '
      security:
      - ClientCredentialsFlow: []
      - AuthorizationCodeFlow: []
      operationId: getProviders
      parameters:
      - name: npis
        in: query
        description: A comma-delimited list of Provider NPI numbers. A maximum of 50 items will be accepted at a time.
        required: true
        schema:
          type: string
          example: 1234567891,0123456789
      - name: insurance_plan_id
        in: query
        description: The Zocdoc ID of the patient's insurance plan. Used to determine if provider takes patient's insurance in response. Use the [Get Insurance Plans](#operation/getInsurancePlans) endpoint to retrieve available plans.
        required: false
        schema:
          type: string
          example: ip_2224
      - name: latitude
        in: query
        description: Latitude of the patient's location. Must be provided together with longitude. When provided, response includes distance and nearest match for each physical location.
        required: false
        schema:
          type: number
          format: float
          minimum: -90
          maximum: 90
      - name: longitude
        in: query
        description: Longitude of the patient's location. Must be provided together with latitude. When provided, response includes distance and nearest match for each physical location.
        required: false
        schema:
          type: number
          format: float
          minimum: -180
          maximum: 180
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderResult'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /v1/providers/{provider_id}/reviews:
    get:
      tags:
      - providers
      description: Get review summary for a provider by their Zocdoc provider ID.
      security:
      - ClientCredentialsFlow: []
      - AuthorizationCodeFlow: []
      operationId: getProviderReviews
      parameters:
      - name: provider_id
        in: path
        description: The Zocdoc provider ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderReviewsResponse'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
      summary: Get Provider Reviews
components:
  schemas:
    BaseResult:
      required:
      - request_id
      type: object
      properties:
        request_id:
          type: string
          description: Unique request identifier for tracing
    BaseProvider:
      type: object
      properties:
        provider_id:
          type: string
          description: The Zocdoc provider ID
        npi:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        title:
          type: string
        full_name:
          type: string
        gender_identity:
          type: string
          description: 'Possible values include: Female, Male, Non-binary'
        specialties:
          type: array
          items:
            type: string
        specialty_ids:
          type: array
          items:
            type: string
        default_visit_reason_id:
          type: string
        visit_reason_ids:
          type: array
          items:
            type: string
        statement:
          type: string
        provider_photo_url:
          type: string
          description: Protocol-relative URL to a provider's photo. URL will change if a new photo is uploaded. Only 1 photo URL will be given at a time. Photos should be 200-4,000 pixels. JPEG and PNG formats are accepted. Photos are reviewed at time of upload and on an annual basis.
          example: //d2uur722ua7fvv.cloudfront.net/ZeeFace_02.svg
        languages:
          type: array
          items:
            type: string
          description: Languages spoken at the practice location, might be facilitated by translators on site.
          example:
          - English
          - Spanish
        profile_url:
          type: string
          description: The URL to view the providers profile on Zocdoc.
          example: https://zocdoc.com/doctor/capivarudo-nojeira-md-517507?utm_source=FakeSource
        credentials:
          $ref: '#/components/schemas/ProviderCredentials'
    ProviderCredentials:
      type: object
      required:
      - certifications
      - education
      properties:
        certifications:
          type: array
          items:
            type: string
        education:
          $ref: '#/components/schemas/Education'
      description: Provider Credentials include education and certifications.
    Error:
      required:
      - message
      type: object
      properties:
        field:
          type: string
        message:
          type: string
    ProviderReviewsResponse:
      allOf:
      - $ref: '#/components/schemas/BaseResult'
      - type: object
        required:
        - data
        properties:
          data:
            $ref: '#/components/schemas/ProviderReviewsData'
    ProvidersByNpi:
      type: object
      properties:
        npi:
          type: string
        providers:
          type: array
          items:
            $ref: '#/components/schemas/ProviderDetails'
    Location:
      allOf:
      - $ref: '#/components/schemas/BaseProviderDetailsLocation'
      - $ref: '#/components/schemas/BaseLocationWithDistance'
      - type: object
        properties:
          is_nearest_match:
            type: boolean
            description: True for the location closest to the provided latitude/longitude. Only populated when latitude and longitude query parameters are provided.
    Practice:
      type: object
      required:
      - practice_id
      - practice_name
      properties:
        practice_id:
          type: string
        practice_name:
          type: string
    ProviderDetails:
      allOf:
      - $ref: '#/components/schemas/BaseProvider'
      - type: object
        required:
        - locations
        - virtual_locations
        - practice
        properties:
          locations:
            type: array
            items:
              $ref: '#/components/schemas/Location'
          virtual_locations:
            type: array
            items:
              $ref: '#/components/schemas/VirtualLocation'
          practice:
            $ref: '#/components/schemas/Practice'
    BaseLocation:
      type: object
      required:
      - address1
      - city
      - state
      - zip_code
      - latitude
      - longitude
      properties:
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
        state:
          description: The location's two letter state code.
          example: NY
          type: string
        zip_code:
          description: The location's 5 digit zip code.
          type: string
        latitude:
          type: number
          format: float
        longitude:
          type: number
          format: float
        location_name:
          type: string
        phone_number:
          type: string
          description: Unformatted phone number for the location. Returns null for certain API products.
          example: '9999999999'
        phone_extension:
          type: string
          description: Unformatted extension digits for the location phone number.
          example: '123'
        time_zone:
          type: string
          description: IANA time zone identifier for the location, e.g., America/New_York.
          example: America/New_York
    BookingRequestInsuranceSource:
      type: string
      description: The types of insurance coverage that a provider accepts
      enum:
      - in_network
      - out_of_network
      - self_pay
    ErrorResult:
      allOf:
      - $ref: '#/components/schemas/BaseResult'
      - type: object
        required:
        - error_type
        - errors
        properties:
          error_type:
            $ref: '#/components/schemas/ErrorType'
          errors:
            type: array
            items:
              $ref: '#/components/schemas/Error'
    ProviderResult:
      allOf:
      - $ref: '#/components/schemas/BaseResult'
      - type: object
        required:
        - data
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/ProvidersByNpi'
        description: Data that will be returned upon a provider lookup.
    BaseLocationWithDistance:
      allOf:
      - $ref: '#/components/schemas/BaseLocation'
      - type: object
        properties:
          distance_to_patient_mi:
            type: number
            format: float
            description: Distance from patient to provider in miles.
    VirtualLocation:
      allOf:
      - $ref: '#/components/schemas/BaseProviderDetailsLocation'
      - $ref: '#/components/schemas/BaseVirtualLocation'
    ErrorType:
      type: string
      enum:
      - api_error
      - invalid_request
    AcceptsPatientInsuranceType:
      type: string
      description: Whether the provider location accepts the patient's insurance
      enum:
      - accepted
      - not_accepted
      - insurance_not_specified
    Education:
      type: object
      properties:
        institutions:
          type: array
          items:
            type: string
    BookingRequirements:
      type: object
      required:
      - required_fields
      - accepts_booking_requests_from
      properties:
        required_fields:
          type: array
          items:
            type: string
            description: Options include `data.patient.insurance.insurance_plan_id` and `data.patient.insurance.insurance_member_id`
        accepts_booking_requests_from:
          type: array
          items:
            $ref: '#/components/schemas/BookingRequestInsuranceSource'
      description: Criteria for booking appointments, defines requirements and mandatory fields specified by Zocdoc providers
    BaseVirtualLocation:
      type: object
      required:
      - state
      properties:
        state:
          description: The location's two letter state code.
          example: NY
          type: string
        location_name:
          type: string
        time_zone:
          type: string
          description: IANA time zone identifier for the location, e.g., America/New_York.
          example: America/New_York
    ProviderReviewsData:
      type: object
      required:
      - provider_id
      - total_reviews
      properties:
        provider_id:
          type: string
          description: The Zocdoc provider ID
        total_reviews:
          type: integer
          description: Total number of reviews for the provider
        average_overall_rating:
          type: number
          format: double
          description: The average overall rating of the provider (1-5), rounded to 1 decimal place
        average_bedside_rating:
          type: number
          format: double
          description: The average bedside rating of the provider (1-5), rounded to 1 decimal place
        average_wait_time_rating:
          type: number
          format: double
          description: The average wait time rating of the provider (1-5), rounded to 1 decimal place
    BaseProviderDetailsLocation:
      type: object
      required:
      - provider_location_id
      - accepts_patient_insurance
      - booking_requirements
      properties:
        provider_location_id:
          type: string
          example: pr_abc123-def456_wxyz7890|lo_abc123-def456_wxyz7890
        accepts_patient_insurance:
          $ref: '#/components/schemas/AcceptsPatientInsuranceType'
        first_availability_date_in_provider_local_time:
          type: string
          format: date
          description: The first date where provider has availability for new patients with any visit reason in provider's local time zone, formatted as YYYY-MM-DD and up to 90 days in the future.
        booking_requirements:
          $ref: '#/components/schemas/BookingRequirements'
  securitySchemes:
    ClientCredentialsFlow:
      type: oauth2
      description: 'Machine to machine authentication (for use from client server to Zocdoc).

        Production: `https://auth.zocdoc.com/oauth/token`

        Sandbox: `https://auth-api-developer-sandbox.zocdoc.com/oauth/token`

        '
      flows:
        clientCredentials:
          tokenUrl: https://auth.zocdoc.com/oauth/token
          scopes:
            external.credential.rotate: Rotate the authenticated client secret.
            external.appointment.write: Book and modify appointments.
            external.appointment.read: Read basic details of your appointments.
            external.anonymous_token.write: Create anonymous tokens used for discovery endpoints.
            external.provider_insurance.write: Update the insurance accepted by a provider.
            external.schedulable_entity.read: Read schedulable entities.
    AuthorizationCodeFlow:
      type: oauth2
      description: 'Log in as a user. Client Secret is not necessary for this login flow.

        Production: `https://auth.zocdoc.com`

        Sandbox: `https://auth-api-developer-sandbox.zocdoc.com`

        '
      flows:
        authorizationCode:
          x-usePkce: true
          tokenUrl: https://auth.zocdoc.com/oauth/token
          authorizationUrl: https://auth.zocdoc.com/authorize
          scopes:
            external.appointment.write: Book and modify appointments.
            external.appointment.read: Read basic details of your appointments.
            external.schedulable_entity.read: Read schedulable entities.