Search availability

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.

Permissions:APPOINTMENTS_READ

Try in API Explorer

Link to section

Request body

Example code

Link to section

query

Required

Query conditions used to filter buyer-accessible booking availabilities.

Link to section

Response fields

Link to section

availabilities

List of appointment slots available for booking.

Link to section

errors

Errors that occurred during the request.

Link to section

Examples

POST /v2/bookings/availability/search

curl https://connect.squareup.com/v2/bookings/availability/search \
  -X POST \
  -H 'Square-Version: 2024-11-20' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "start_at_range": {
          "start_at": "2020-11-26T13:00:00Z",
          "end_at": "2020-11-27T13:00:00Z"
        },
        "location_id": "LEQHH0YY8B42M",
        "segment_filters": [
          {
            "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
            "team_member_id_filter": {
              "any": [
                "TMXUrsBWWcHTt79t",
                "TMaJcbiRqPIGZuS9"
              ]
            }
          }
        ]
      }
    }
  }'

Response JSON

{
  "availabilities": [
    {
      "start_at": "2020-11-26T13:00:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMXUrsBWWcHTt79t",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-26T13:30:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMXUrsBWWcHTt79t",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-26T14:00:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMaJcbiRqPIGZuS9",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-26T14:30:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMaJcbiRqPIGZuS9",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-26T15:00:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMaJcbiRqPIGZuS9",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-26T15:30:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMaJcbiRqPIGZuS9",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-26T16:00:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMaJcbiRqPIGZuS9",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-27T09:00:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMXUrsBWWcHTt79t",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-27T09:30:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMaJcbiRqPIGZuS9",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-27T10:00:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMXUrsBWWcHTt79t",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-27T10:30:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMXUrsBWWcHTt79t",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-27T11:00:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMXUrsBWWcHTt79t",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-27T11:30:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMaJcbiRqPIGZuS9",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-27T12:00:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMaJcbiRqPIGZuS9",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-27T12:30:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMaJcbiRqPIGZuS9",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-27T13:00:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMXUrsBWWcHTt79t",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-27T13:30:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMXUrsBWWcHTt79t",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    },
    {
      "start_at": "2020-11-27T14:00:00Z",
      "location_id": "LEQHH0YY8B42M",
      "appointment_segments": [
        {
          "duration_minutes": 60,
          "team_member_id": "TMaJcbiRqPIGZuS9",
          "service_variation_id": "RU3PBTZTK7DXZDQFCJHOK2MC",
          "service_variation_version": 1599775456731
        }
      ]
    }
  ],
  "errors": []
}