--- title: "SearchAvailability" method: POST path: "/v2/bookings/availability/search" tags: ["Bookings"] --- # SearchAvailability `POST /v2/bookings/availability/search` Searches for availabilities for booking. To call this endpoint with buyer-level permissions, set `APPOINTMENTS_READ` for the OAuth scope. To call this endpoint with seller-level permissions, set `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope. ## Request body - SearchAvailabilityRequest - `query` SearchAvailabilityQuery, required — The query used to search for buyer-accessible availabilities of bookings. - `filter` SearchAvailabilityFilter, required — A query filter to search for buyer-accessible availabilities by. - `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. - `start_at` string, nullable — A datetime value in RFC 3339 format indicating when the time range starts. - `end_at` string, nullable — A datetime value in RFC 3339 format indicating when the time range ends. - `location_id` string, nullable — The query expression to search for buyer-accessible availabilities with their location IDs matching the specified location ID. This query expression cannot be set if `booking_id` is set. - `segment_filters` SegmentFilter[], nullable — The query expression to search for buyer-accessible availabilities matching the specified list of segment filters. If the size of the `segment_filters` list is `n`, the search returns availabilities with `n` segments per availability. This query expression cannot be set if `booking_id` is set. - `service_variation_id` string, required — The ID of the [CatalogItemVariation](entity:CatalogItemVariation) object 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[], nullable — A list of terms that must be present on the field of the resource. - `any` string[], nullable — A list of terms where at least one of them must be present on the field of the resource. - `none` string[], nullable — A list of terms that must not be present on the field the resource - `booking_id` string, nullable — The query expression to search for buyer-accessible availabilities for an existing booking by matching the specified `booking_id` value. This is commonly used to reschedule an appointment. If this expression is set, the `location_id` and `segment_filters` expressions cannot be set. ## Response `200` Success - SearchAvailabilityResponse - `availabilities` Availability[] — List of appointment slots available for booking. - `start_at` string, nullable — The RFC 3339 timestamp specifying the beginning time of the slot available for booking. - `location_id` string — The ID of the location available for booking. - `appointment_segments` AppointmentSegment[], nullable — The list of appointment segments available for booking - `duration_minutes` integer, nullable — The time span in minutes of an appointment segment. - `service_variation_id` string, nullable — The ID of the [CatalogItemVariation](entity:CatalogItemVariation) object representing the service booked in this segment. - `team_member_id` string, required — The ID of the [TeamMember](entity:TeamMember) object representing the team member booked in this segment. - `service_variation_version` integer, nullable — The current version of the item variation representing the service booked in this segment. - `intermission_minutes` integer — Time between the end of this segment and the beginning of the subsequent segment. - `any_team_member` boolean — Whether the customer accepts any team member, instead of a specific one, to serve this segment. - `resource_ids` string[] — The IDs of the seller-accessible resources used for this appointment segment. - `errors` Error[] — Errors that occurred during the request. - `category` 'API_ERROR' | 'AUTHENTICATION_ERROR' | 'INVALID_REQUEST_ERROR' | 'RATE_LIMIT_ERROR' | 'PAYMENT_METHOD_ERROR' | 'REFUND_ERROR' | 'MERCHANT_SUBSCRIPTION_ERROR' | 'EXTERNAL_VENDOR_ERROR', required — Indicates which high-level category of error has occurred during a request to the Connect API. - `code` 'INTERNAL_SERVER_ERROR' | 'UNAUTHORIZED' | 'ACCESS_TOKEN_EXPIRED' | 'ACCESS_TOKEN_REVOKED' | 'CLIENT_DISABLED' | 'FORBIDDEN' | 'INSUFFICIENT_SCOPES' | 'APPLICATION_DISABLED' | 'V1_APPLICATION' | 'V1_ACCESS_TOKEN' | 'CARD_PROCESSING_NOT_ENABLED' | 'MERCHANT_SUBSCRIPTION_NOT_FOUND' | 'BAD_REQUEST' | 'MISSING_REQUIRED_PARAMETER' | 'INCORRECT_TYPE' | 'INVALID_TIME' | 'INVALID_TIME_RANGE' | 'INVALID_VALUE' | 'INVALID_CURSOR' | 'UNKNOWN_QUERY_PARAMETER' | 'CONFLICTING_PARAMETERS' | 'EXPECTED_JSON_BODY' | 'INVALID_SORT_ORDER' | 'VALUE_REGEX_MISMATCH' | 'VALUE_TOO_SHORT' | 'VALUE_TOO_LONG' | 'VALUE_TOO_LOW' | 'VALUE_TOO_HIGH' | 'VALUE_EMPTY' | 'ARRAY_LENGTH_TOO_LONG' | 'ARRAY_LENGTH_TOO_SHORT' | 'ARRAY_EMPTY' | 'EXPECTED_BOOLEAN' | 'EXPECTED_INTEGER' | 'EXPECTED_FLOAT' | 'EXPECTED_STRING' | 'EXPECTED_OBJECT' | 'EXPECTED_ARRAY' | 'EXPECTED_MAP' | 'EXPECTED_BASE64_ENCODED_BYTE_ARRAY' | 'INVALID_ARRAY_VALUE' | 'INVALID_ENUM_VALUE' | 'INVALID_CONTENT_TYPE' | 'INVALID_FORM_VALUE' | 'CUSTOMER_NOT_FOUND' | 'ONE_INSTRUMENT_EXPECTED' | 'NO_FIELDS_SET' | 'TOO_MANY_MAP_ENTRIES' | 'MAP_KEY_LENGTH_TOO_SHORT' | 'MAP_KEY_LENGTH_TOO_LONG' | 'CUSTOMER_MISSING_NAME' | 'CUSTOMER_MISSING_EMAIL' | 'INVALID_PAUSE_LENGTH' | 'INVALID_DATE' | 'UNSUPPORTED_COUNTRY' | 'UNSUPPORTED_CURRENCY' | 'APPLE_TTP_PIN_TOKEN' | 'CARD_EXPIRED' | 'INVALID_EXPIRATION' | 'INVALID_EXPIRATION_YEAR' | 'INVALID_EXPIRATION_DATE' | 'UNSUPPORTED_CARD_BRAND' | 'UNSUPPORTED_ENTRY_METHOD' | 'INVALID_ENCRYPTED_CARD' | 'INVALID_CARD' | 'PAYMENT_AMOUNT_MISMATCH' | 'GENERIC_DECLINE' | 'CVV_FAILURE' | 'ADDRESS_VERIFICATION_FAILURE' | 'INVALID_ACCOUNT' | 'CURRENCY_MISMATCH' | 'INSUFFICIENT_FUNDS' | 'INSUFFICIENT_PERMISSIONS' | 'CARDHOLDER_INSUFFICIENT_PERMISSIONS' | 'INVALID_LOCATION' | 'TRANSACTION_LIMIT' | 'VOICE_FAILURE' | 'PAN_FAILURE' | 'EXPIRATION_FAILURE' | 'CARD_NOT_SUPPORTED' | 'READER_DECLINED' | 'INVALID_PIN' | 'MISSING_PIN' | 'MISSING_ACCOUNT_TYPE' | 'INVALID_POSTAL_CODE' | 'INVALID_FEES' | 'MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED' | 'PAYMENT_LIMIT_EXCEEDED' | 'GIFT_CARD_AVAILABLE_AMOUNT' | 'ACCOUNT_UNUSABLE' | 'BUYER_REFUSED_PAYMENT' | 'DELAYED_TRANSACTION_EXPIRED' | 'DELAYED_TRANSACTION_CANCELED' | 'DELAYED_TRANSACTION_CAPTURED' | 'DELAYED_TRANSACTION_FAILED' | 'CARD_TOKEN_EXPIRED' | 'CARD_TOKEN_USED' | 'AMOUNT_TOO_HIGH' | 'UNSUPPORTED_INSTRUMENT_TYPE' | 'REFUND_AMOUNT_INVALID' | 'REFUND_ALREADY_PENDING' | 'PAYMENT_NOT_REFUNDABLE' | 'PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE' | 'REFUND_ERROR_PAYMENT_NEEDS_COMPLETION' | 'REFUND_DECLINED' | 'INSUFFICIENT_PERMISSIONS_FOR_REFUND' | 'INVALID_CARD_DATA' | 'SOURCE_USED' | 'SOURCE_EXPIRED' | 'UNSUPPORTED_LOYALTY_REWARD_TIER' | 'LOCATION_MISMATCH' | 'ORDER_UNPAID_NOT_RETURNABLE' | 'PARTIAL_PAYMENT_DELAY_CAPTURE_NOT_SUPPORTED' | 'IDEMPOTENCY_KEY_REUSED' | 'UNEXPECTED_VALUE' | 'SANDBOX_NOT_SUPPORTED' | 'INVALID_EMAIL_ADDRESS' | 'INVALID_PHONE_NUMBER' | 'CHECKOUT_EXPIRED' | 'BAD_CERTIFICATE' | 'INVALID_SQUARE_VERSION_FORMAT' | 'API_VERSION_INCOMPATIBLE' | 'CARD_PRESENCE_REQUIRED' | 'UNSUPPORTED_SOURCE_TYPE' | 'CARD_MISMATCH' | 'PLAID_ERROR' | 'PLAID_ERROR_ITEM_LOGIN_REQUIRED' | 'PLAID_ERROR_RATE_LIMIT' | 'PAYMENT_SOURCE_NOT_ENABLED_FOR_TARGET' | 'CARD_DECLINED' | 'VERIFY_CVV_FAILURE' | 'VERIFY_AVS_FAILURE' | 'CARD_DECLINED_CALL_ISSUER' | 'CARD_DECLINED_VERIFICATION_REQUIRED' | 'BAD_EXPIRATION' | 'CHIP_INSERTION_REQUIRED' | 'ALLOWABLE_PIN_TRIES_EXCEEDED' | 'RESERVATION_DECLINED' | 'UNKNOWN_BODY_PARAMETER' | 'NOT_FOUND' | 'APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'NOT_ACCEPTABLE' | 'REQUEST_TIMEOUT' | 'CONFLICT' | 'GONE' | 'REQUEST_ENTITY_TOO_LARGE' | 'UNSUPPORTED_MEDIA_TYPE' | 'UNPROCESSABLE_ENTITY' | 'RATE_LIMITED' | 'NOT_IMPLEMENTED' | 'BAD_GATEWAY' | 'SERVICE_UNAVAILABLE' | 'TEMPORARY_ERROR' | 'GATEWAY_TIMEOUT', required — Indicates the specific error that occurred during a request to a Square API. - `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/connect-api.md) · [All operations](https://skmtc.net/square/apis/connect-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/connect-api/versions/6a5164284e41/schema)