Zocdoc
Zocdoc calendar-integration-timeslots API

Endpoints to manage timeslots for providers.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  version: '1.176'
  title: API Documentation appointments calendar-integration-timeslots 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: calendar-integration-timeslots
  description: Endpoints to manage timeslots for providers.
  x-displayName: Calendar integration timeslots
paths:
  /v1/providers/{provider_id}/calendar/timeslots:
    get:
      tags:
      - calendar-integration-timeslots
      description: Get timeslots for a provider and date.
      operationId: getProviderCalendarTimeslots
      parameters:
      - name: provider_id
        in: path
        required: true
        schema:
          type: string
          example: pr_abc123-def456_wxyz7890
      - name: date
        in: query
        required: true
        description: The date for which to get timeslots in YYYY-MM-DD format. This parameter will match against the local date part of the time slot's `start_time`. For example, a timeslot with start_time of 2024-10-01T22:00 and time_zone of America/New_York is considered 2024-10-01 when querying timeslots, even though it resolves to 2024-10-02 in UTC.
        schema:
          type: string
          format: date
          example: '2024-10-26'
      - name: next_page_token
        in: query
        required: false
        description: A token to get the next set of results.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: The limit of objects to get in the response. For this endpoint, this is equivalent to page_size.
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeslotListResponse'
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      summary: Get timeslots for provider on date
    put:
      description: "This endpoint sets the complete list of available slots for a specific provider on a specific date. Each request must include the entire set of slots for that date. If a provider wishes to list times at multiple locations for a single date, each location must have its own timeslot object added to the array. A new request made for the same provider and date will overwrite the previous set of slots. If you send an empty array, all slots for that provider across all locations on that date will be deleted.\n\n**Note**: The timeslots are stored in an eventually consistent data store. This means there is a small\npossibility that a fetch might not include recently created slots if you fetch timeslots immediately after inserting them.\n\n**Parameter Validations**:\n* The user must have access to the specified `provider_id`.\n\n**Validations for each timeslot in the request body**:\n* `slot.provider_id`:\n    * Must match the `provider_id` specified in the endpoint parameter.\n* `slot.start_time`:\n    * Must be a valid \"local date-time\" string in ISO 8601 format, e.g., `2024-09-15T12:13:00`. The seconds component is optional.\n    * The date component must match the `date` parameter.\n* `slot.time_zone`:\n    * Must be a valid IANA time zone ID (e.g., `America/New_York` or `America/Denver`).\n"
      operationId: putProviderCalendarTimeslots
      tags:
      - calendar-integration-timeslots
      parameters:
      - name: provider_id
        in: path
        required: true
        schema:
          type: string
          example: pr_abc123-def456_wxyz7890
      - name: date
        in: query
        required: true
        description: The date for which to put timeslots in YYYY-MM-DD format.
        schema:
          type: string
          format: date
          example: '2024-10-16'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeslotPutRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeslotPutResponse'
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      summary: Put provider calendar timeslots
components:
  schemas:
    CalendarIntegrationTimeslotWeb:
      description: A bookable appointment start time for a particular provider
      type: object
      required:
      - timeslot_id
      - created_utc
      properties:
        provider_id:
          type: string
          description: Provider id
          example: pr_abc123-def456_wxyz7890
        location_id:
          type: string
          description: Location id
          example: lo_abc123-def456_wxyz7890
        start_time:
          type: string
          format: date-time-local
          description: The local date and time within the timezone. The seconds may be omitted.
          example: '2024-09-03T09:30:00'
        time_zone:
          type: string
          description: The IANA time zone id of the timeslot's start time.
          example: America/New_York
        allowed_visit_reason_ids:
          type: array
          description: 'Restrict the timeslot to these visit reasons. Both `null` and an empty array will not restrict the timeslot.


            Can work in conjunction with `excluded_visit_reason_ids`. `allowed_visit_reason_ids` are superceded by `excluded_visit_reason_ids`.

            So if a visit reason is included in both `allowed_visit_reason_ids` and `excluded_visit_reason_ids`, the net effect is that visit reason

            being excluded.


            | allowed | excluded | => Result |

            | -----   | -------- | --------- |

            | null    | null     | all visit reasons allowed |

            | [A,B]   | null     | only A & B are allowed |

            | null    | [A,B]    | all visit reasons except A & B are allowed |

            | [A,B]   | [B,C]    | only A is allowed (C is irrelevant) |

            | [A,B]   | [A,B]    | No visit reasons allowed, unbookable timeslot |

            '
          items:
            type: string
          example:
          - pc_FRO-18leckytNKtruw5dLR
        excluded_visit_reason_ids:
          type: array
          items:
            type: string
          example:
          - pc_TlZW-r06U0W3pCsIGtSI5B
          description: 'Exclude these visit reasons. Both `null` and an empty array means no visit reasons will be excluded.


            Can work in conjunction with `allowed_visit_reason_ids`. `allowed_visit_reason_ids` are superceded by `excluded_visit_reason_ids`.

            So if a visit reason is included in both `allowed_visit_reason_ids` and `excluded_visit_reason_ids`, the net effect is that visit reason

            being excluded.


            | allowed | excluded | => Result |

            | -----   | -------- | --------- |

            | null    | null     | all visit reasons allowed |

            | [A,B]   | null     | only A & B are allowed |

            | null    | [A,B]    | all visit reasons except A & B are allowed |

            | [A,B]   | [B,C]    | only A is allowed (C is irrelevant) |

            | [A,B]   | [A,B]    | No visit reasons allowed, unbookable timeslot |

            '
        patient_type:
          $ref: '#/components/schemas/PatientType'
        timeslot_id:
          type: string
          description: Timeslot id
          example: slot:ab123
        created_utc:
          type: string
          format: instant
          description: the time this timeslot was created in Zocdoc's system.
          example: '2024-01-01T09:30:00Z'
    BaseResult:
      required:
      - request_id
      type: object
      properties:
        request_id:
          type: string
          description: Unique request identifier for tracing
    TimeslotPutResponse:
      type: object
      properties:
        errors:
          $ref: '#/components/schemas/TimeslotPutErrors'
    TimeslotPutErrors:
      type: object
      required:
      - not_found_location_ids
      properties:
        not_found_location_ids:
          type: array
          items:
            type: string
          description: Location IDs that were not found on the Zocdoc side.
    TimeslotPutRequest:
      required:
      - timeslots
      type: object
      properties:
        timeslots:
          type: array
          minItems: 0
          maxItems: 1500
          items:
            $ref: '#/components/schemas/TimeslotBaseRequest'
    TimeslotBaseRequest:
      description: a bookable appointment start time for a particular provider
      type: object
      required:
      - provider_id
      - start_time
      - location_id
      - time_zone
      properties:
        provider_id:
          type: string
          description: Provider id
          example: pr_abc123-def456_wxyz7890
        location_id:
          type: string
          description: Location id
          example: lo_abc123-def456_wxyz7890
        start_time:
          type: string
          format: date-time-local
          description: the local date and time within the timezone. The seconds may be omitted.
          example: '2024-10-16T09:30:00'
        time_zone:
          type: string
          description: The IANA time zone id of the appointment. Must be valid.
          example: America/New_York
        allowed_visit_reason_ids:
          type: array
          description: 'Restrict the timeslot to these visit reasons. Both `null` and an empty array will not restrict the timeslot.


            Can work in conjunction with `excluded_visit_reason_ids`. `allowed_visit_reason_ids` are superceded by `excluded_visit_reason_ids`.

            So if a visit reason is included in both `allowed_visit_reason_ids` and `excluded_visit_reason_ids`, the net effect is that visit reason

            being excluded.


            | allowed | excluded | => Result |

            | -----   | -------- | --------- |

            | null    | null     | all visit reasons allowed |

            | [A,B]   | null     | only A & B are allowed |

            | null    | [A,B]    | all visit reasons except A & B are allowed |

            | [A,B]   | [B,C]    | only A is allowed (C is irrelevant) |

            | [A,B]   | [A,B]    | No visit reasons allowed, unbookable timeslot |

            '
          items:
            type: string
          example:
          - pc_TlZW-r06U0W3pCsIGtSI5B
        excluded_visit_reason_ids:
          type: array
          items:
            type: string
          example:
          - pc_TAZW-r16U0B3pZeIutSI3L
          description: 'Exclude these visit reasons. Both `null` and an empty array means no visit reasons will be excluded.


            Can work in conjunction with `allowed_visit_reason_ids`. `allowed_visit_reason_ids` are superceded by `excluded_visit_reason_ids`.

            So if a visit reason is included in both `allowed_visit_reason_ids` and `excluded_visit_reason_ids`, the net effect is that visit reason

            being excluded.


            | allowed | excluded | => Result |

            | -----   | -------- | --------- |

            | null    | null     | all visit reasons allowed |

            | [A,B]   | null     | only A & B are allowed |

            | null    | [A,B]    | all visit reasons except A & B are allowed |

            | [A,B]   | [B,C]    | only A is allowed (C is irrelevant) |

            | [A,B]   | [A,B]    | No visit reasons allowed, unbookable timeslot |

            '
        patient_type:
          $ref: '#/components/schemas/PatientType'
    PatientType:
      type: string
      description: Whether or not the patient has been to the provider's practice.
      enum:
      - existing
      - new
      example: new
    IteratedBaseResult:
      allOf:
      - $ref: '#/components/schemas/BaseResult'
      - type: object
        properties:
          limit:
            type: integer
            description: 'Maximum number of items requested.

              Note: For DynamoDB-style pagination, this may not match the number of items returned.

              '
          next_page_token:
            type: string
            description: Opaque cursor token for the next page. Null if no more pages.
          next_url:
            type: string
            description: Complete URL for fetching the next page (convenience field)
    TimeslotListResponse:
      allOf:
      - $ref: '#/components/schemas/IteratedBaseResult'
      - type: object
        description: A list of timeslots.
        required:
        - data
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/CalendarIntegrationTimeslotWeb'
  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.
Zocdoc calendar-integration-timeslots API

Documentation

Specifications

Other Resources

OpenAPI Specification
