Search Availability

Returns the available start times of a lane: an ordered list of services that one client
takes back to back, each with an optional provider. Every start time is broken down per service,
with every provider who can take it.

Important Notes

  • Requires available_slots:read scope (it is a read, sent as POST because it carries a body).
  • location_id, start_date and services are required. services is ordered: the first service
    starts at the start time and each next one when the previous ends. The same service may appear
    more than once. A lane of one service is the simple case.
  • services takes at most 10 items; a longer lane answers 400 max_services_exceeded before
    any search.
  • provider_id is per service. When omitted, any eligible provider of the location can take that
    service; a start time is returned only if every service of the lane fits with some provider
    (and a time resource when the service needs one).
  • Start times are aligned to the clock: multiples of the company's booking interval (leap,
    15 minutes by default) from midnight. A gap whose only fitting start is off that grid is not
    offered (GET /v3/available_slots may offer it).
  • Each times[].services[] entry lists in providers every provider free for that service at
    that time, least occupied first. Book with one of them; a service that needs a time resource
    also carries time_resource_id (one free resource) and time_resource_ids (all of them).
  • There is no end_time: add each service's duration (in metadata.services) to its
    start_time.
  • dates_and_providers blocks times you are already holding (for example, the lane of another
    person of the same group): each entry marks that provider as busy between start_time and
    end_time. Entries that are not valid times are ignored.
  • The company's minimum notice and booking window apply. The provider's online booking setting
    does not: a provider hidden from the online booking site is offered too.
  • Services with options that must be chosen cannot be searched through this API
    (422 invalid_service_options.bundled_missing or invalid_service_options.cardinality).
  • Each item of services and dates_and_providers is filtered to the fields documented below.

Errors Dictionary

Business errors arrive with their key in error and no detail (see Errors).

StatusErrorDetailDescription
400invalid_bodyexpected_objectRequest body is not a JSON object.
400invalid_formatservicesservices is not a list of objects.
400invalid_formatdates_and_providersdates_and_providers is not a list of objects.
400max_services_exceededservicesMore than 10 services in services.
400missing_services—services is missing or empty.
400invalid_location_id · invalid_service_id · invalid_provider_id—The id is not an integer.
400invalid_date—start_date is not a valid date.
400invalid_provider—provider_id is a time resource, not a provider.
401unauthorizedinvalid_api_keyMissing or invalid Bearer token.
401unauthorizedapi_config_inactiveAPI access is inactive for this company.
403forbiddenscope_deniedAPI key lacks available_slots:read scope.
404location_not_found · service_not_found—The location or a service does not exist or belongs to another company.
422date_in_the_past—start_date is in the past.
422date_beyond_booking_window—start_date is beyond the company's booking window.
422no_eligible_providers—No provider of the location can take a service of the lane that day.
422location_is_not_active · service_is_not_active · service_provider_is_not_active—The location, a service or a provider is not active.
422cross_company_service—A service belongs to another company.
422cross_location_service_provider—A provider does not work at the location.
422provider_not_offering_service—A provider does not offer its service.
422invalid_service_options.bundled_missing · invalid_service_options.cardinality—The service has options that must be chosen.
429rate_limitedburst_limit_exceededPer-minute request limit exceeded.
429rate_limiteddaily_quota_exceededDaily request quota exceeded.
502upstream_unavailableconnection_failedThe upstream service is unavailable.
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
integer
required
date
required

Date to search (POST /v3/availability) or first date to try (first_available).

services
array of objects
required
length between 1 and 10

The lane, in booking order.

services*
integer
required
integer | null

Only this provider for this service. Omitted or null, any eligible provider.

dates_and_providers
array of objects

Times to treat as busy for a provider (for example, held for another lane).

dates_and_providers
Responses

Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json