---
title: "Search Appointment Slots"
method: POST
path: "/v1/appointments/slots"
---

# Search Appointment Slots

`POST /v1/appointments/slots`

## Request

- Base URL: `https://app.untetherlabs.com/api`
- URL: `https://app.untetherlabs.com/api/v1/appointments/slots`
- Auth: HTTP bearer

<Warning>This is a beta endpoint. Breaking changes may occur without notice, use at your own risk.</Warning>

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.

## Request body

- SearchAppointmentSlotsRequest
  - `appointmentTypeId` string, required
  - `startDate` string, required
  - `endDate` string, required
  - `requirements` object: Hard filters for possible slots
    - `providerIds` string[]
    - `skill` union
      - SkillRequirementCondition
        - `type` 'equal', required
        - `skill` string, required
        - `value` string, required
      - SkillRequirementGroup
        - `type` 'and' | 'or', required
        - `entries` union[], required
          - union
            - SkillRequirementCondition
              - …
            - SkillRequirementNestedGroup
              - …
  - `preferences` object: Soft filters for possible slots
    - `providerIds` string[]
    - `skill` union
      - SkillRequirementCondition
        - `type` 'equal', required
        - `skill` string, required
        - `value` string, required
      - SkillRequirementGroup
        - `type` 'and' | 'or', required
        - `entries` union[], required
          - union
            - SkillRequirementCondition
              - …
            - SkillRequirementNestedGroup
              - …
  - `limit` number: Maximum number of slots to return

## Response `201`

- SearchAppointmentSlotsResponse
  - `results` AppointmentSlot[], required
    - `score` number, required: Arbitrary number for ranking slots relative to each other. Should not be compared to anything besides the appointments returned by this request.
    - `appointmentTypeId` string, required
    - `startDate` string, required
    - `endDate` string, required
    - `providerId` string, required

## Other responses

- `400`: 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.
- `404`: 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.

---

[API](https://skmtc.dev/untetherlabs/apis/untether-labs-api.md) - [All operations](https://skmtc.dev/untetherlabs/apis/untether-labs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/untetherlabs/apis/untether-labs-api/revisions/143223935df3?raw)