Skip to content

List bookable appointment slots

GET
/api/book/{slug}/availability

The public availability grid, the same one a business's booking page draws.

Slot allocation is first-come: for a given start time the first staff member found free wins it. Slots whose start time has already passed are filtered out, because the booking POST rejects them anyway.

Ranged mode (days). Answers up to 14 consecutive days from date in one request. The single-date shape ({slots}) stays the default; days greater than 1 switches the response to {days: {"<date>": {slots}, ...}}, one entry per requested date.

Path Parameters

slug*string

The organization's public booking slug, i.e. the {slug} in /{slug}. Only orgs with status active resolve; anything else is a 404.

Query Parameters

service_id*string

One active service id of this business, or up to six comma-separated for a multi-service visit. The slot maths runs on the SUM of the durations, and a specific staff member must offer EVERY id; with any, eligibility is the intersection and one person carries the whole block. Any id unknown, inactive, or not this business's makes the whole request a 404; more than six is a 400.

date*string

YYYY-MM-DD. Interpreted as a UTC wall clock, the same convention computeAvailableSlots uses. The first day answered in ranged mode.

Formatdate
addons?string

Visits P5. Add-ons ticked per service, as serviceId:addonId pairs, comma-separated. Each must be one of the live add-ons of this venue offered with a service in service_id, else 400. Its minutes lengthen that service at the end (after any processing), so slots are offered for the longer visit.

provider_id?string

Omit, or send any, to search every provider offering the service. A specific id that is not an active provider of this org offering this service returns an EMPTY slot list, not a 404; returning 404 would let a caller probe which provider ids exist.

days?integer

How many consecutive days from date to answer in one call. Omitted or 1 keeps the original single-date {slots} shape; 2 to 14 switches the response to {days: {"<date>": {slots}, ...}}.

Range1 <= value <= 14
manage_token?string

Present only when the guest manage page calls this route to pick a new time for an existing booking. Governs which notice policy gates the slots returned, since a reschedule cannot reuse the ordinary minimum-notice rule unchanged.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/book/string/availability?service_id=string&date=2019-08-24"
{  "slots": [    {      "startsAt": "2019-08-24T14:15:22Z",      "providerId": "4834bcdc-4a64-444d-966b-1a6fe381da24",      "lines": [        {          "serviceId": "8f8bb40f-b96b-40fe-9064-5031fbe483f9",          "providerId": "4834bcdc-4a64-444d-966b-1a6fe381da24"        }      ]    }  ],  "reason": "string",  "banner": "string",  "notices": {    "property1": {      "dateNote": "string",      "closedReason": "string"    },    "property2": {      "dateNote": "string",      "closedReason": "string"    }  }}