> ## Documentation Index > Fetch the complete documentation index at: https://developers.untetherlabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Search Appointment Slots This is a beta endpoint. Breaking changes may occur without notice, use at your own risk. Generate appointment slot suggestions for a set of available providers in the given time range. Slots are based on working-type shifts in the period, filtered & ranked by the given requirements/preferences. On ranking, * Skills are ranked by the closest match. For example, a skill requirement for specialty X will rank providers with only specialty X highly, and providers with multiple specialties including X lower. * Slots which do not create unusable gaps are preferred. Skills are the primary mechanism for selecting providers, see [Using Skills](/guides/skills) for more information. ## OpenAPI ````yaml /openapi.json post /v1/appointments/slots openapi: 3.1.0 info: version: 1.0.0 title: Untether Labs API servers: - url: https://app.untetherlabs.com/api description: Untether Labs Production API x-speakeasy-server-id: production security: - BearerAuth: [] paths: /v1/appointments/slots: post: summary: ' Search Appointment Slots' operationId: v1_appointments_slots_searchAppointmentSlots requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchAppointmentSlotsRequest' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/SearchAppointmentSlotsResponse' '400': description: >- We follow the [RFC-9457](https://www.rfc-editor.org/rfc/rfc9457.html) Problem Detail specification for error responses. Errors should be identified by their `type` field. You can view extensions for each error response below. content: application/problem+json: schema: oneOf: - allOf: - type: object properties: type: type: string status: type: integer description: Always the HTTP status code of the response example: 400 title: type: string description: >- A short, human-readable summary of the problem type detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem example: >- The specified provider does not satisfy the skill requirements for this shift. required: - type - status - title - type: object properties: path: type: string message: type: string type: type: string enum: - >- https://developers.untetherlabs.com/errors#validation title: type: string example: Input validation failed. required: - message - type - title title: Validation '404': description: >- We follow the [RFC-9457](https://www.rfc-editor.org/rfc/rfc9457.html) Problem Detail specification for error responses. Errors should be identified by their `type` field. You can view extensions for each error response below. content: application/problem+json: schema: oneOf: - allOf: - type: object properties: type: type: string status: type: integer description: Always the HTTP status code of the response example: 400 title: type: string description: >- A short, human-readable summary of the problem type detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem example: >- The specified provider does not satisfy the skill requirements for this shift. required: - type - status - title - type: object properties: type: type: string enum: - >- https://developers.untetherlabs.com/errors#appointment-type-not-found title: type: string example: >- A specified appointmenttype does not exist in the system. required: - type - title title: AppointmentType Not Found components: schemas: SearchAppointmentSlotsRequest: type: object properties: appointmentTypeId: type: string startDate: type: string example: 2024-11-20T07:43:34+0000 endDate: type: string example: 2024-11-20T07:43:34+0000 requirements: type: object properties: providerIds: type: array items: type: string skill: $ref: '#/components/schemas/SkillRequirement' additionalProperties: {} x-speakeasy-group: v1.appointments description: Hard filters for possible slots preferences: type: object properties: providerIds: type: array items: type: string skill: $ref: '#/components/schemas/SkillRequirement' additionalProperties: {} x-speakeasy-group: v1.appointments description: Soft filters for possible slots limit: type: number default: 10 description: Maximum number of slots to return required: - appointmentTypeId - startDate - endDate id: SearchAppointmentSlotsRequest x-speakeasy-group: v1.appointments SearchAppointmentSlotsResponse: type: object properties: results: type: array items: $ref: '#/components/schemas/AppointmentSlot' required: - results id: SearchAppointmentSlotsResponse x-speakeasy-group: v1.appointments SkillRequirement: anyOf: - $ref: '#/components/schemas/SkillRequirementCondition' - $ref: '#/components/schemas/SkillRequirementGroup' id: SkillRequirement x-speakeasy-group: v1.settings.skill-requirement-templates AppointmentSlot: type: object properties: score: type: number description: >- Arbitrary number for ranking slots relative to each other. Should not be compared to anything besides the appointments returned by this request. appointmentTypeId: type: string startDate: type: string example: 2024-11-20T07:43:34+0000 endDate: type: string example: 2024-11-20T07:43:34+0000 providerId: type: string required: - score - appointmentTypeId - startDate - endDate - providerId id: AppointmentSlot x-speakeasy-group: v1.appointments SkillRequirementCondition: type: object properties: type: type: string enum: - equal skill: type: string minLength: 1 value: type: string required: - type - skill - value id: SkillRequirementCondition x-speakeasy-group: v1.settings.skill-requirement-templates SkillRequirementGroup: type: object properties: type: type: string enum: - and - or x-fern-enum: and: {} or: {} entries: type: array items: anyOf: - $ref: '#/components/schemas/SkillRequirementCondition' - $ref: '#/components/schemas/SkillRequirementNestedGroup' minItems: 1 required: - type - entries id: SkillRequirementGroup x-speakeasy-group: v1.settings.skill-requirement-templates SkillRequirementNestedGroup: type: object properties: type: type: string enum: - and - or x-fern-enum: and: {} or: {} entries: type: array items: $ref: '#/components/schemas/SkillRequirementCondition' minItems: 1 required: - type - entries id: SkillRequirementNestedGroup x-speakeasy-group: v1.settings.skill-requirement-templates securitySchemes: BearerAuth: type: http scheme: bearer ````