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.