x-api-key header. The first three answer “when is someone free?” for a
single session; the last two build complete N-session plans for a
package:
Every endpoint on this page is authenticated with the
x-api-key header,
not Authorization. See Authentication.The two package endpoints have package-specific anatomy — slate and slot
shapes, cadence rules, the 120-day look-ahead ceiling, cadence relaxation,
and the hold/convert path. They’re summarised below and documented in full
in Availability and slates.
Search (who-is-available)
serviceId, offeringId, and either locationId
or both lat and lng. Omitting the location entirely is a 400.
daysOfWeek is a hard allow-list, not a preference. A weekday you
leave out is removed from the pool before the engine searches — no
matching slot can land on it. If your UI collects the inverse (exception
chips like “No Sundays” the client toggles on), invert the selection
before sending it: pass the days that remain allowed, not the ones the
client excluded.excludeDates (individual LOCAL blackout dates, no range form) is a
related field, but it isn’t part of this endpoint’s request — it’s
specific to package-slate and package-options. See
Availability and slates.timeSlots / openSlots and errors: [].
searchId identifies this search; it is also the X-MB-Search-Id header.
suppliers lists each supplier that appears in timeSlots or openSlots,
with its position: the 0-based rank of its first slot, timeSlots first.
Keep the searchId for the session, and report what you draw with it. See
Report site events.
Slot times and zones
Every slot intimeSlots[] and openSlots[] carries the same instant twice:
The envelope’s
timezone is the zone actually used to render
timeSlotDateAndTime and to bucket days: the request timezone, or the
project default when you sent none. If your code reads the clock digits
rather than parsing the whole string, send timezone explicitly.
supplierZones maps each supplier that appears in the slot arrays to their
own profile zone. Use it as the bookingTz for a virtual booking with no
service location — the location’s zone wins when there is one, then the
supplier’s, then the project default. A supplier missing from the map has no
profile zone; fall back to the project default.
Search ids on every availability route
Every route on this page returns asearchId, in the body and in the
X-MB-Search-Id header:
/suppliers— the samesearchIdon every page (the cursor keeps it), and each supplier aposition, continuous across pages.package-slate— asearchId, and each slate apositionacross the whole response.package-options— asearchId, and each slate apositionwithin its package.time-slots— asearchId, but nothing from it is logged for insights.
X-MB-Session-Key (an opaque session key, at most 64
characters) and X-MB-Client-Kind (browser, server, monitor or
loadtest).
How offered times are worked out
These rules apply to/search, /suppliers and /time-slots.
Travel fields on a slot
Each suggested slot intimeSlots[] says how it was placed:
Accept every
travelType value. The start and end values appear only when
the project uses start and end of day locations.
Split shifts
When a supplier’s day has a break, each block of the day is treated on its own. A break comes from two time ranges on one weekday, two schedules on one date, or blocked time in the middle of a range. Each block offers its own first and last time. On an empty day of 9:00–13:00 and 15:00–18:00, a 30-minute service is offered at 9:00, 12:30, 15:00 and 17:30. Ranges that touch, such as 9:00–13:00 and 13:00–17:00, are one block. AFROM-PREVIOUS-BOOKING or TO-NEXT-BOOKING time can be on the other side
of a break. Don’t assume it comes right after, or right before, the booking
it refers to. travelTimeMins still gives the real drive.
Open slots leave time to drive
Open slots leave time for the supplier to drive from the booking before and to the booking after. That drive is an estimate from the straight-line distance, rounded up to 5 minutes. A booking within 50 m of the requested place counts as the same place, so back-to-back times there are still offered. Your project’s open-slot buffer applies on top. Where roads are slower than the estimate, an open slot can still need an override when staff book it.Drive times account for traffic
Each drive is timed for the time of day it happens. A drive at rush hour takes longer, so rush-hour times can move later or disappear. The supplier’s maximum travel time is checked against the drive with traffic. Don’t cache drive times across times of day.A buffer before the service
A service’sbufferBeforeStartMinutes (0–120) leaves a gap before a job of
that service in suggested times. It isn’t busy time, and it isn’t part of
travelTimeMins. A booking made at a specific time is never refused because
of it.
Start and end of day locations
A project can let a supplier’s schedule set where their working day starts and ends. It’s off by default. See Start and end of day locations. Once it’s on and a supplier has set locations:- The first and last times of a day can shift, because the drive from the start location and to the end location counts.
- Slots can carry
FROM-START-LOCATIONorTO-END-LOCATION. - A slot with
travelDistance: nullwas placed against a drive that couldn’t be routed. On such a slot,travelTimeMins: 0doesn’t mean there’s no travel. - No availability response contains a supplier’s start or end address or coordinates.
What errors[] can contain
errors[] entries are strings. A supplier named in one has a partial or
empty result. That doesn’t mean they have no availability.
Recurring search
To find a repeating slot pattern, setbookingType to recurring
and pass an rrule. The recurring branch returns pattern objects
(mostAvailableStartTime, startTimeConsistencyPercent) in
timeSlots[] rather than individual slots.
Recurring requests have one strict requirement, a 400 if not met:
lookAheadStartDate is any ISO-8601 instant — a Z suffix and a numeric
offset are equally valid. The window and the recurrence anchor are resolved
on the local date in the request timezone, so a midnight-UTC start
against a zone west of Greenwich anchors on the previous local day. A value
that does not parse is a 400.
Time-slots (direct engine)
{ config, suppliers[] }:
config— engine settings:targetGeoLocation,targetServiceDurationMins,lookAheadStartDate/lookAheadEndDate,distanceUnit,sortBy,timezone, and so on.suppliers[]— each withsupplierId,maxTravelTimeMins,bufferTimeMins, anavailability[]array (each with anrrule),bookings[], andblockedTime[].
suppliers is a 400. The response adds metrics and kpis
to the slot list.
metrics.totalTravelTimeRequestsMadecounts the distinct drives (direction, place) answered for the whole request, shared across all suppliers. A failed or unroutable drive isn’t counted.- Each slot’s
travelDistanceis the distance of the drive the slot was placed on. - A recurring availability window in a zone ahead of UTC lands on the
weekdays you wrote. For example, a Monday window at
09:00+11:00is served on Mondays. - Counts and slot distances changed on 2026-11-12. A payload captured before then can replay with different counts, distances and labels, and can gain slots.
Suppliers (grouped by supplier)
/search, pivoted: instead of flat
slot arrays you get a paginated list of suppliers, each with its full
profile (the same shape as GET /suppliers) and its open slots bucketed by
local day. Use it to render a wall of supplier cards with bookable times.
Required: serviceId, offeringId, and either locationId or
both lat and lng — the same location rule as /search.
Notes that catch people out:
- It returns regular-interval open slots only — no clustered or
travel-optimized suggestions, and no recurrence patterns. Use
/searchfor those. - Suppliers that match the service and location but have no availability
in the window are still returned, with
days: []. Filter client-side if you only want bookable ones. - Paginate with
limit(max 50) plus the opaquecursor.nextCursorisnullon the last page. - Each slot carries a UTC anchor (
startUtc/endUtc) plus*Localstrings rendered in the requesttimezone, with that zone’s offset at that instant.startUtcis the engine’stimeSlotStartUtcverbatim.
Rank suppliers by fit: availabilityMatch
Four new optional request fields describe the schedule you actually want,
rather than just a window to search. Three of them — plus the pre-existing
lookAheadStartDate — feed the availabilityMatch score below;
excludeDates instead filters the slot pool and has no score component:
availabilityMatch is produced by four scoring criteria:
lookAheadStartDate, preferredTimes, daysOfWeek, and sessionsPerWeek.
Send any of those four and each supplier in data[] gains an
availabilityMatch object next to supplier and days:
scoreis the plain, unrounded mean of thecomponentspresent — renormalised over only the criteria you sent, not divided by 4. Sending one preference can legitimately score a supplier1.0.componentscarries exactly one key per field you sent:startDateforlookAheadStartDate(present only when you explicitly send it — its denominator is the local dates your window actually spans, notlookAheadDays),timeOfDayforpreferredTimes,daysOfWeekfordaysOfWeek,sessionsPerWeekforsessionsPerWeek.- Suppliers with no matching availability are still returned, with
score: 0— never dropped from the page. availabilityMatchis omitted entirely, notnull, when none oflookAheadStartDate,preferredTimes,daysOfWeekorsessionsPerWeekis sent.excludeDatesalone does not produce one — it filters the slot pool instead of scoring it, so a request carrying onlyexcludeDatesgets the same response shape as before this field existed.- Ranking only holds within a page — page membership is decided before
any availability is computed, so a supplier on page 2 can outscore every
supplier on page 1. See the full breakdown, including the
sessionsPerWeek-week anddaysOfWeek-denominator details, in Search suppliers by availability.
Package slate (a complete N-session plan)
packageId (the session count, service and
offering are derived from it) — or, to plan what is left on a credit the
client already owns, its orderId and orderItemId, optionally with the clientId the order must
belong to — plus a location, an IANA timezone, a
lookAheadStartDate carrying a numeric offset, and an rrule with a bounded
COUNT. The returned primarySlate.slateId books the whole plan in one call
via POST /v1/projects/{projectId}/orders/{orderId}/package-bookings.
Two cadence guards apply, each a 400 VALIDATION_ERROR: lookAheadStartDate
must carry a numeric ±HH:MM offset rather than a Z suffix (the slate
builder reads the offset from the last six characters — unlike recurring
search, which now accepts either form), and rrule must carry a bounded,
positive COUNT. Every session in the returned slate is stamped with
bookingTz equal to its home zone — the service location’s zone, else
the supplier’s, else the project default — not the timezone you sent.
Responses are 200 when anything is bookable and 422 when nothing is —
specifically, when primarySlate, partial and cadenceAlternatives
are all empty.
Planning from a credit uses its remaining sessions (quantityRemaining
replaces the rrule’s COUNT), its own service and offering, and ends at its
expiresAt. It works after the package was deleted. Send exactly one source:
neither or both is a 400. A credit that can’t be planned is refused before
any search: 409 ORDER_CANCELLED, 409 ORDER_ITEM_QUANTITY_UNAVAILABLE (no
sessions left), 409 PACKAGE_EXPIRED, 400 NOT_A_PACKAGE_ITEM,
400 INVALID_ORDER_REFERENCE, or 404 NOT_FOUND for an unknown item. See
Create a package booking.
Cadence relaxation. By default a supplier who can’t meet your exact
rrule yields a 422. Opt in with cadenceFlexibility (or
guaranteeSlate) and the response instead carries cadenceAlternatives:
complete N-session plans at a denser, supplier-feasible cadence, each
directly bookable, under status: "ALTERNATIVE_CADENCE" — a success,
returned as 200. A request that sets neither field sees no change
whatsoever. Fully documented in
Availability and slates.Package options (every package of a service)
package-slate: returns every ACTIVE package of a
service, each with its own complete N-session plan and ready-to-book
slateId. Cadence defaults to FREQ=WEEKLY;COUNT={creditCount}, derived per
package. It accepts the same cadence-relaxation fields.
Unlike package-slate, it is always 200 — a package that can’t be
planned comes back with its own status and reason rather than failing the
whole request.
Errors
/search, /suppliers and /time-slots report engine failures differently:
inside a 200, as strings in the body’s errors[]. An empty result with a
non-empty errors is a broken search, not an empty calendar.
See Errors for the full error envelope.
Endpoint index
POST /v1/projects/{projectId}/availability/searchPOST /v1/projects/{projectId}/availability/time-slotsPOST /v1/projects/{projectId}/availability/suppliersPOST /v1/projects/{projectId}/availability/package-slatePOST /v1/projects/{projectId}/availability/package-options