Skip to main content
Availability is the public face of the MarketBox clustering engine. Given a service, a location, and a window of time, it returns the slots a supplier can realistically be booked into — accounting for existing bookings, schedules, and travel time between jobs. There are five endpoints, all project-scoped and authenticated with the 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)

You pass a service, an offering, and a discovery location; the API resolves matching suppliers from project data and returns suggested slots, open slots, and (for recurring requests) recurrence patterns. Required: 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.
The response envelope:
No matching suppliers returns the same envelope with empty timeSlots / openSlots and errors: [].
A failed search is still a 200. The engine reports failures as strings in errors[], not as an HTTP error. Empty slots with a non-empty errors means the search broke, not that nobody is free. Check errors before you tell a client there is no availability. /availability/suppliers behaves the same way.
Check engineEnabled before you say nobody is free. It is false when the project has switched its scheduling engine off. The engine then doesn’t run, so timeSlots is empty because it wasn’t computed, not because nobody is free. openSlots is unaffected.
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 in timeSlots[] 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 a searchId, in the body and in the X-MB-Search-Id header:
  • /suppliers — the same searchId on every page (the cursor keeps it), and each supplier a position, continuous across pages.
  • package-slate — a searchId, and each slate a position across the whole response.
  • package-options — a searchId, and each slate a position within its package.
  • time-slots — a searchId, but nothing from it is logged for insights.
You may tag any of them with two optional headers, stored for insights and never acted on: 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 in timeSlots[] 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. A FROM-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’s bufferBeforeStartMinutes (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-LOCATION or TO-END-LOCATION.
  • A slot with travelDistance: null was placed against a drive that couldn’t be routed. On such a slot, travelTimeMins: 0 doesn’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. To find a repeating slot pattern, set bookingType 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:
rrule must include a bounded COUNT (e.g. FREQ=WEEKLY;BYDAY=TU;COUNT=3). The builder expands each occurrence set to COUNT dates and needs a slot on every one; an unbounded rule defaults to 10 occurrences and almost always returns nothing.
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)

The lower-level endpoint. Instead of resolving suppliers from project data, you pass them in: their availability, existing bookings, and an engine config. Use it when you already hold the scheduling state and just want the engine’s clustering + travel-time logic. The body is { config, suppliers[] }:
  • config — engine settings: targetGeoLocation, targetServiceDurationMins, lookAheadStartDate / lookAheadEndDate, distanceUnit, sortBy, timezone, and so on.
  • suppliers[] — each with supplierId, maxTravelTimeMins, bufferTimeMins, an availability[] array (each with an rrule), bookings[], and blockedTime[].
Omitting suppliers is a 400. The response adds metrics and kpis to the slot list.
  • metrics.totalTravelTimeRequestsMade counts 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 travelDistance is 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:00 is 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)

The same single-session availability as /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 /search for 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 opaque cursor. nextCursor is null on the last page.
  • Each slot carries a UTC anchor (startUtc / endUtc) plus *Local strings rendered in the request timezone, with that zone’s offset at that instant. startUtc is the engine’s timeSlotStartUtc verbatim.

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:
  • score is the plain, unrounded mean of the components present — renormalised over only the criteria you sent, not divided by 4. Sending one preference can legitimately score a supplier 1.0.
  • components carries exactly one key per field you sent: startDate for lookAheadStartDate (present only when you explicitly send it — its denominator is the local dates your window actually spans, not lookAheadDays), timeOfDay for preferredTimes, daysOfWeek for daysOfWeek, sessionsPerWeek for sessionsPerWeek.
  • Suppliers with no matching availability are still returned, with score: 0 — never dropped from the page.
  • availabilityMatch is omitted entirely, not null, when none of lookAheadStartDate, preferredTimes, daysOfWeek or sessionsPerWeek is sent. excludeDates alone does not produce one — it filters the slot pool instead of scoring it, so a request carrying only excludeDates gets 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 and daysOfWeek-denominator details, in Search suppliers by availability.

Package slate (a complete N-session plan)

Builds a slate — a complete N-session plan for a package, from a single supplier’s availability. Pass a 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)

The composite built on 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/search
  • POST /v1/projects/{projectId}/availability/time-slots
  • POST /v1/projects/{projectId}/availability/suppliers
  • POST /v1/projects/{projectId}/availability/package-slate
  • POST /v1/projects/{projectId}/availability/package-options