POST /v1/projects/{projectId}/availability/suppliers: a
supplier-centric availability search. You give it a service, a location,
and a window; it returns a paginated list of suppliers, each with its full
profile and its open slots bucketed by local day. It’s built for one job —
rendering a wall of supplier cards (“here are the people who can do this,
and when”) — for a human UI or an AI agent assembling one.
It builds on The booking engine model — read
that first if you haven’t. It also assumes the
BFF pattern and an API key already
set up.
Which availability endpoint
There are four availability endpoints plus the supplier list. They answer different questions — pick by what you’re rendering:/availability/suppliers and /availability/search run the same open-slot
computation over the same project data. The only difference is the shape of
the answer: /suppliers groups by supplier and inlines each supplier’s full
profile, so a card wall needs exactly one call. /search hands you flat slot
arrays keyed by an opaque supplierId — fine when you want a single merged
list of times, but you’d have to group and then fetch each supplier to label a
card.How it works
One request in, one page of suppliers out: The endpoint returns open slots only — every regular-interval opening in the window (interval controls the granularity). It does not return the
clustered, travel-optimized suggestions that /search and /package-slate
produce, and it has no recurring mode. That’s deliberate: a wall wants “every
time you could book this person,” not a ranked shortlist.
The response, supplier-centric
Each slot carries both a UTC anchor and pre-formatted local strings:
Busy suppliers are still returned, with
days: []. A supplier who serves
the service and location but has no opening in your window comes back in
data with an empty days array, not dropped. That’s intentional: it keeps
each page deterministic (a page is exactly limit matching suppliers), and it
lets you render a “no times this week” card instead of silently hiding
someone. Filter them client-side if you only want bookable cards
(data.filter(s => s.days.length > 0)).Why there are fewer slots next to bookings
Open slots leave time for the supplier to drive from the booking before and to the booking after. The drive is estimated from the straight-line distance and rounded up to 5 minutes. A booking within 50 m counts as the same place, so back-to-back times there are still offered. A few more rules shape the slots you get:- When a supplier’s day has a break, each block of the day offers its own first and last time.
- Drives are timed with traffic, so rush-hour times can move later or disappear.
- A service’s
bufferBeforeStartMinutesleaves a gap before each job of that service. - If the project uses start and end of day locations, a supplier’s first and last times can shift.
Build the wall
1
Search suppliers by availability
From your BFF, POST the service + offering, a location (either a stored
locationId or a lat/lng pair), and the window. Keep the API key
server-side.2
Render the cards
The response is already card-shaped — map Show
data straight to components, and
supplier.days straight to day columns. No grouping, no per-supplier fetch.startLocal/endLocal to the user; keep startUtc/endUtc for the
booking call in the next step.3
Page through more suppliers
Each supplier’s availability is computed on demand, so pages are small by
design (
limit max 50, default 20). When nextCursor isn’t null, pass
it back as cursor to fetch the next page; stop when it’s null.4
Book the chosen slot
A slot is availability, not a reservation. When the client picks one, book it
immediately with Create a single booking —
the slot gives you everything the booking’s timing needs:Choose the location and zone. A slot carries times only — no
locationId and no zone. Take them from how you searched and from the
supplier on the card:page.timezone is the zone you asked to see the slots in — usually the
viewer’s. Don’t send it as bookingTz: a viewer in another zone would
stamp the booking’s local date and time in the wrong zone.Rank suppliers by fit: availabilityMatch
Four optional scoring criteria shape a per-supplier fit score:
lookAheadStartDate — a field you may already be sending — plus three new
ones: preferredTimes, daysOfWeek, sessionsPerWeek. Send any of the four
and every supplier in the response grows an availabilityMatch object next
to supplier and days:
availabilityMatch is omitted, not null, when you send none of the four
scoring criteria above. A bare request — just serviceId, offeringId,
and a location — gets a byte-identical response to before this field
existed. Don’t assume the key exists; check for it before reading .score.scoreis the plain mean of the components you triggered, 0–1, renormalised over only the criteria you supplied — not divided by 4. Send one preference and a supplier can score a clean1.0; that’s correct, not a bug. Without renormalising, sending a single preference would cap every supplier at 0.25.componentscontains exactly the keys for the fields you sent — a key only appears when its matching request field was present.- No rounding. Expect long floats like
0.8035714285714286, not0.8. - Each component is a coverage ratio, not a slot count. A supplier with 200 open slots isn’t a better fit than one with 40 if both cover the pattern you asked for equally well — counting slots would just rank the busiest calendar top, which is the opposite of what a fit score is for.
The four components
startDate itself only appears when you explicitly send
lookAheadStartDate — even though the field always has an effective value
(it defaults to now), sending nothing means no criterion was expressed, so
nothing is scored or averaged in. This is what lets a request with none of
the four scoring criteria come back with no availabilityMatch at all.
Two more behaviours worth knowing:
sessionsPerWeekcounts consecutive 7-day blocks from the start of your window, not ISO/Monday weeks, and a trailing partial week isn’t scored — a 10-day window has exactly one scored week; slots in the leftover 3 days still count toward the other three components. A window shorter than 7 days is evaluated as a single week at the full, un-prorated threshold.daysOfWeek’s denominator is the weekdays you requested, so a window shorter than a week caps the component below1— asking for[1, 3, 5]over a 4-day window can reach at most2/3. Widen the window if you need the component to be reachable.
preferredTimes windows may cross midnight. { "startTime": "22:00", "endTime": "02:00" } matches a slot starting at 23:00 and one starting at
01:00 — when startTime > endTime the window is read as spanning
midnight. Membership is inclusive at both ends.
excludeDates removes slots; it doesn’t lower a score. A blacked-out
date never appears in days[] for any supplier, and excludeDates has no
component in availabilityMatch. The filter runs against the slot pool
before the four components are computed, so a blackout influences a score
exactly as much as it shows up in the response — not at all.
Suppliers with no matching availability still get an entry — with
score: 0, not dropped. Every supplier on the page is scored, in page order. Page
size and nextCursor behave exactly as they do without availabilityMatch.Worked example
A request supplying all four scoring criteria, plusexcludeDates:
windowDays
equals lookAheadDays here — see the warning above for when it doesn’t).
startDate is 1 - 2/14: the supplier’s first slot, on 2026-07-09, lands
two days in. timeOfDay is 2/3: of the three days with any availability
(07-09, 07-13, 07-15), two carry a slot that starts inside the
17:00–20:00 window — 07-15’s slots all start outside it. daysOfWeek
is also 2/3: of the requested [1, 3, 5] (Mon/Wed/Fri), the supplier
covers Monday (07-13) and Wednesday (07-15) but not Friday — it simply
has no slots on 2026-07-17, the window’s other Friday. (2026-07-10, the
Friday you excluded, never had a slot to remove — excludeDates isn’t why
Friday scores zero here.) sessionsPerWeek is 1/2: the window’s two whole
7-day blocks are 07-07–07-13 and 07-14–07-20; the first holds two
distinct days with a slot (07-09 and 07-13), meeting the requested
threshold of 2, and the second holds only one (07-15), missing it.
2026-07-10 itself is simply absent from days[] — excluded dates never
appear there, empty or otherwise. score is the exact mean of the four:
(0.8571428571428572 + 0.6666666666666666 + 0.6666666666666666 + 0.5) / 4.
Notes on the window and timezone
timezone decides the day buckets. Days are bucketed by local calendar
date in the request timezone (or the project default if you omit it) — so
the same UTC instant can land on different dates for clients in different
zones. The *Local fields are rendered in that same zone. If your UI shows
day columns, always send the viewer’s timezone.No matching suppliers is a
200, not an error. If no supplier serves the
service at that location, you get { "data": [], "nextCursor": null }. Widen
the location or the window, or check who covers the point with
GET /suppliers?lat=…&lng=… — it
needs no service or offering, so it separates “nobody serves here” from
“nobody is free this week”.Reference
Endpoints used in this guide
Request fields
Configuration
Errors and edge cases
See Errors for the full envelope and code list, and
Pagination for how the opaque
cursor works across
the paginated list endpoints.
Create a single booking
Turn a chosen slot into a confirmed booking — order, order item, then booking.
Availability and slates
The slot-centric
/search endpoint, plus packages, holds, and the clustering engine in depth.Build a supplier profile page
One supplier’s page, with the next opening found through this endpoint.
Suppliers
The full supplier profile shape returned in each card — services, skills, and locations.
The booking engine model
Orders, order items, bookings, and how availability feeds them.