Zocdoc schedulable-entities API

openapi: 3.0.0
info:
  version: '1.177'
  title: API Documentation schedulable-entities API
  description: Endpoints to manage the providers in the developer's directory. Retrieve the schedulable
    entities currently in your directory with availability information, or submit a list of NPIs to determine
    which of those providers are already schedulable.
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 manage the providers in the developer's directory. Retrieve the schedulable
    entities currently in your directory with availability information, or submit a list of NPIs to determine
    which of those providers are already schedulable.
  x-displayName: Directory Management
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
  /v1/schedulable_entities/overlaps:
    put:
      tags:
      - schedulable-entities
      summary: Submit NPI overlaps
      description: 'Submit NPI overlaps to compare your provider directory with providers

        bookable on Zocdoc. Send real-time distribution status

        (`developer_app_state`), unverified addresses and other data required

        for joint provider operations.

        '
      security:
      - ClientCredentialsFlow:
        - external.schedulable_entity.read
      - AuthorizationCodeFlow:
        - external.schedulable_entity.read
      operationId: putSchedulableEntitiesOverlaps
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SchedulableEntitiesOverlapsRequestBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchedulableEntitiesOverlapsResponseBody'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
components:
  schemas:
    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.
    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.
    BaseResult:
      required:
      - request_id
      type: object
      properties:
        request_id:
          type: string
          description: Unique request identifier for tracing
    DeveloperAppStateInput:
      type: string
      enum:
      - disabled
      - enabled
      description: Whether the developer's app is enabled or disabled
    Error:
      required:
      - message
      type: object
      properties:
        field:
          type: string
        message:
          type: string
    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'
    ErrorType:
      type: string
      enum:
      - api_error
      - invalid_request
    MatchRequestInput:
      type: object
      required:
      - npi
      properties:
        npi:
          type: string
          description: National Provider Identifier
        metadata:
          type: array
          items:
            $ref: '#/components/schemas/MatchRequestMetadataItem'
    MatchRequestMetadataItem:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
    MatchRequestResponseItem:
      type: object
      required:
      - npi
      - schedule_state
      - schedulable_entities
      properties:
        npi:
          type: string
          description: National Provider Identifier
        schedule_state:
          $ref: '#/components/schemas/ZocdocSchedulableStatus'
        schedulable_entities:
          type: array
          items:
            $ref: '#/components/schemas/OverlapsSchedulableEntityItem'
    OverlapsSchedulableEntityItem:
      type: object
      required:
      - id
      - entity_type
      properties:
        id:
          type: string
          description: Zocdoc provider location ID (e.g., pr_zzzz|lo_yyyy)
        entity_type:
          $ref: '#/components/schemas/OverlapsSchedulableEntityType'
    OverlapsSchedulableEntityType:
      type: string
      description: Entity type
      enum:
      - provider_location
    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
    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)
    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'
    SchedulableEntitiesOverlapsRequestBody:
      type: object
      required:
      - overlaps
      - developer_app_state
      properties:
        overlaps:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/MatchRequestInput'
        developer_app_state:
          $ref: '#/components/schemas/DeveloperAppStateInput'
    SchedulableEntitiesOverlapsResponseBody:
      allOf:
      - $ref: '#/components/schemas/BaseResult'
      - type: object
        required:
        - data
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/MatchRequestResponseItem'
    SchedulableEntitiesResponse:
      allOf:
      - $ref: '#/components/schemas/PaginatedBaseResult'
      - type: object
        required:
        - data
        properties:
          data:
            $ref: '#/components/schemas/SchedulableEntitiesData'
    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
        main_specialty_id:
          type: string
          description: Zocdoc specialty ID of the provider's main specialty (format sp_<id>). Omitted
            when the provider has no main specialty.
          example: sp_123
        main_specialty_name:
          type: string
          description: Display name of the provider's main specialty. Omitted when the specialty id is
            absent or cannot be resolved.
          example: Cardiologist
    SchedulableEntityType:
      type: string
      enum:
      - provider_location
    ZocdocSchedulableStatus:
      type: string
      enum:
      - schedulable
      - not_schedulable
      - added_to_queue
  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.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.
            external.booking_intent.write: Create and modify booking intents.
            external.booking_intent.read: Read booking intents.
            external.consent.read: Read your partner-connect consent grants.
            external.partner_consent.write: Revoke your partner-connect consent grants.
    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.