---
title: "SearchAvailability"
method: POST
path: "/v2/bookings/availability/search"
tags: ["Bookings"]
---

# SearchAvailability

`POST /v2/bookings/availability/search`

Searches for availabilities for booking.

## Request body

- SearchAvailabilityRequest
  - `query` SearchAvailabilityQuery, required — Query conditions to search for availabilities of bookings.
    - `filter` SearchAvailabilityFilter, required — A query filter to search for availabilities by.
      - `booking_id` string — The query expression to search for availabilities for an existing booking by matching the specified `booking_id` value. This is commonly used to reschedule an appointment. If this expression is specified, the `location_id` and `segment_filters` expressions are not allowed.
      - `location_id` string — The query expression to search for availabilities matching the specified seller location IDs. This query expression is not applicable when `booking_id` is present.
      - `segment_filters` SegmentFilter[] — The list of segment filters to apply. A query with `n` segment filters returns availabilities with `n` segments per availability. It is not applicable when `booking_id` is present.
        - `service_variation_id` string, required — The ID of the [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogItemVariation) representing the service booked in this segment.
        - `team_member_id_filter` FilterValue — A filter to select resources based on an exact field value. For any given value, the value can only be in one property. Depending on the field, either all properties can be set or only a subset will be available. Refer to the documentation of the field.
          - `all` string[] — A list of terms that must be present on the field of the resource.
          - `any` string[] — A list of terms where at least one of them must be present on the field of the resource.
          - `none` string[] — A list of terms that must not be present on the field the resource
      - `start_at_range` TimeRange, required — Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
        - `end_at` string — A datetime value in RFC 3339 format indicating when the time range ends.
        - `start_at` string — A datetime value in RFC 3339 format indicating when the time range starts.

## Response `200`

Success

- SearchAvailabilityResponse
  - `availabilities` Availability[] — List of slots available for booking.
    - `appointment_segments` AppointmentSegment[] — The list of appointment segments available for booking
      - `duration_minutes` integer, required — The time span in minutes of an appointment segment.
      - `service_variation_id` string, required — The ID of the [CatalogItemVariation](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogItemVariation) object representing the service booked in this segment.
      - `service_variation_version` integer, required — The current version of the item variation representing the service booked in this segment.
      - `team_member_id` string, required — The ID of the [TeamMember](https://developer.squareup.com/reference/square_2021-08-18/objects/TeamMember) object representing the team member booked in this segment.
    - `location_id` string — The ID of the location available for booking.
    - `start_at` string — The RFC 3339 timestamp specifying the beginning time of the slot available for booking.
  - `errors` Error[] — Any errors that occurred during the request.
    - `category` string, required — The high-level category for the error.
    - `code` string, required — The specific code of the error.
    - `detail` string — A human-readable description of the error for debugging purposes.
    - `field` string — The name of the field provided in the original request (if any) that the error pertains to.

---

[API](https://skmtc.net/square/apis/squareup.md) · [All operations](https://skmtc.net/square/apis/squareup/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/squareup/revisions/8d95e3639487/schema)