openapi: 3.0.0
info:
  version: '1.176'
  title: API Documentation appointments schedulable-entities 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: schedulable-entities
  description: Endpoints to retrieve schedulable entities with availability information.
  x-displayName: Schedulable entities
paths:
  /v1/schedulable_entities:
    get:
      tags:
      - schedulable-entities
      summary: Get schedulable entities
      description: 'Get the list of schedulable entities within the developer''s Zocdoc directory (provider-locations, etc.) with availability information.


        NPIs can be used to search for providers in the /v1/providers endpoint to facilitate availability, discovery, and booking. Schedulable entity ids can be used to find provider-locations in the /v1/provider_locations/{provider_location_id} endpoint to facilitate availability, discovery, and booking.


        Developers can fetch the schedulable entities list and cache in their system. The available schedulable entities do not change frequently. Pulling this data once a week and/or after known directory change events should be sufficient. However, you may use the `recent_changes_72hrs` parameter and the `recent_change_summary` field to get the list of entities that have changed in the last 72 hours.

        '
      security:
      - ClientCredentialsFlow:
        - external.schedulable_entity.read
      - AuthorizationCodeFlow:
        - external.schedulable_entity.read
      operationId: getSchedulableEntities
      parameters:
      - name: page
        in: query
        description: The zero indexed page of results. A mimimum value of 0 will be accepted.
        required: false
        schema:
          type: integer
      - name: page_size
        in: query
        description: The number of results to return per page. The default value is 5000. A mimimum value of 1 and a maximum of 10000 will be accepted.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 10000
      - name: schedule_types
        in: query
        description: The comma-delimited list of schedule types to include. Will return all schedule types if not provided.
        required: false
        schema:
          type: string
      - name: recent_changes_72hrs
        in: query
        description: When true, only includes entities added or updated in the last 72 hours
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchedulableEntitiesResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
components:
  schemas:
    ErrorType:
      type: string
      enum:
      - api_error
      - invalid_request
    BaseResult:
      required:
      - request_id
      type: object
      properties:
        request_id:
          type: string
          description: Unique request identifier for tracing
    PaginatedBaseResult:
      allOf:
      - $ref: '#/components/schemas/BaseResult'
      - type: object
        required:
        - page
        - page_size
        - total_count
        - next_url
        properties:
          page:
            description: The zero based index of the current page.
            type: integer
          page_size:
            description: The size of the current page.
            type: integer
          total_count:
            description: The total number of result items.
            type: integer
          next_url:
            description: A link to the next page of results; null if this is the last page of results.
            type: string
    SchedulableEntityType:
      type: string
      enum:
      - provider_location
    RecentChangeSummary:
      type: object
      required:
      - schedulable_entities_added
      - schedulable_entities_removed
      - schedulable_entities_profile_updated
      properties:
        schedulable_entities_added:
          type: array
          items:
            type: string
          description: A provider location was activated
        schedulable_entities_removed:
          type: array
          items:
            type: string
          description: A provider location was deactivated
        schedulable_entities_profile_updated:
          type: array
          items:
            type: string
          description: provider or location profile data changed (NPI, name, specialty, address, default visit reason)
    AvailabilityStatus:
      type: string
      enum:
      - none
      - limited
      - available
      description: The availability status of the schedulable entity for the next 28 days. Limited availablility means that the entity has less than 20 timeslots available for the next 28 days.
    SchedulableEntitiesResponse:
      allOf:
      - $ref: '#/components/schemas/PaginatedBaseResult'
      - type: object
        required:
        - data
        properties:
          data:
            $ref: '#/components/schemas/SchedulableEntitiesData'
    Error:
      required:
      - message
      type: object
      properties:
        field:
          type: string
        message:
          type: string
    SchedulableEntitiesData:
      type: object
      required:
      - recent_change_summary
      - schedulable_entities
      properties:
        recent_change_summary:
          $ref: '#/components/schemas/RecentChangeSummary'
        schedulable_entities:
          type: array
          items:
            $ref: '#/components/schemas/SchedulableEntity'
    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'
    SchedulableEntity:
      type: object
      required:
      - id
      - type
      - go_live_timestamp_utc
      - profile_last_modified_timestamp_utc
      - new_patient_availability
      - existing_patient_availability
      properties:
        id:
          type: string
        npi:
          type: string
        type:
          $ref: '#/components/schemas/SchedulableEntityType'
        go_live_timestamp_utc:
          type: string
          format: date-time
          description: The timestamp when the schedulable entity became available in the developer's directory.
        profile_last_modified_timestamp_utc:
          type: string
          format: date-time
          description: The timestamp when the schedulable entity's profile was last modified in the developer's directory. This includes basic information on the provider and location records.
        new_patient_availability:
          $ref: '#/components/schemas/AvailabilityInfo'
        existing_patient_availability:
          $ref: '#/components/schemas/AvailabilityInfo'
        time_zone:
          type: string
          description: IANA time zone identifier for the location, e.g., America/New_York.
          example: America/New_York
    AvailabilityInfo:
      type: object
      required:
      - next_28_days
      - url
      properties:
        next_available_utc:
          type: string
          format: date-time
          description: The next available date and time in UTC, across all visit reasons, up to 90 days in the future.
        next_28_days:
          $ref: '#/components/schemas/AvailabilityStatus'
        url:
          type: string
          description: The GET URL to receive the schedulable entity's availability in this API for their default visit reason and the corresponding patient type.
  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.