Skip to main content
This guide covers 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 bufferBeforeStartMinutes leaves 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.
See How offered times are worked out.
A supplier named in errors[] has a partial result. days: [], or fewer days than expected, can mean a drive couldn’t be routed, not that the supplier is busy. Check errors before you show “no times this week”. The entries you can see each start with SupplierError or SupplierWarning and name the supplier.

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.
Provide a location exactly one way. Send either locationId (a stored Location) or both lat and lng (in-home / travel-zone discovery) — sending neither is a 400. lat/lng is the branch to use when the client enters an address; locationId when they pick a fixed venue.
2

Render the cards

The response is already card-shaped — map data straight to components, and supplier.days straight to day columns. No grouping, no per-supplier fetch.
Show 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.
cursor is opaque — a base64 token, not a supplier offset you should build yourself. Only ever pass back a nextCursor you were given, and only against the same filter set (same service, location, and window) that produced it. Changing the filters mid-pagination gives undefined results.
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.
A search result is not a reservation. These are open slots — another client can take the same time until you actually claim it, and you’ll get a 409 SLOT_BOOKED if they beat you to it.If you need to reserve the time while the client pays, hold it: POST /holds with an intervals array works for a single session, with no package or slate involved, and you then convert the hold into the booking. Each interval carries the same location contract as a booking — { supplierId, startUtc, endUtc, bookingTz, locationType, … }, where locationType decides whether locationId, latitude, longitude and address come with it. See Hold slots during checkout.

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.
  • score is 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 clean 1.0; that’s correct, not a bug. Without renormalising, sending a single preference would cap every supplier at 0.25.
  • components contains 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, not 0.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’s denominator is the local dates your window actually spans — not lookAheadDays. A window that doesn’t open at local midnight reaches one calendar date further than lookAheadDays suggests, and the default path doesn’t open at midnight: an omitted lookAheadStartDate resolves to now, and any minimum-booking-notice policy can shift it later still. Concretely, a window opening Tuesday 14:00 with lookAheadDays: 7 runs through the following Tuesday 14:00 — that’s eight local dates, not seven. The two only coincide when the window happens to end at exact local midnight.
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:
  • sessionsPerWeek counts 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 below 1 — asking for [1, 3, 5] over a 4-day window can reach at most 2/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.
daysOfWeek ranks here; it’s a hard filter on /availability/package-slate. Same field name, opposite behaviour. On this endpoint, a weekday you leave out of daysOfWeek is never removed from a supplier’s days[] — it only lowers that supplier’s daysOfWeek component and therefore their score. Compare daysOfWeek is a hard filter, not a preference on package-slate, where the same field name removes days from the plan before it’s built.
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.
Ranking only holds within a single page. availabilityMatch.score is comparable between suppliers in the same response — it is not a globally ranked list across pages. Page membership is decided by supplier id (sorted, then sliced) before any availability or score is computed, so a supplier on page 2 can legitimately outscore every supplier on page 1. This is deliberate: it bounds the cost of the endpoint, since each supplier’s availability is computed on demand. Don’t paginate expecting suppliers to arrive in descending score order — sort/filter within a page instead, or pull every page before ranking across the whole set.

Worked example

A request supplying all four scoring criteria, plus excludeDates:
The matching response fragment for one supplier, with all four components present:
The window is a clean 14 local dates (midnight-aligned, so 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.