Skip to main content
POST
Supplier-centric availability: paginated suppliers, each with open slots grouped by day

Authorizations

x-api-key
string
header
required

API key minted in the MarketBox dashboard. Scope is restricted to the projects you select at creation time. Every route needs the key's standard API access (*) except POST /v1/projects/{projectId}/events, which needs events:write; a key without * is refused with 403 CAPABILITY_NOT_GRANTED.

Path Parameters

projectId
string
required

The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.

Minimum string length: 1
Example:

"prj_01kv60qgnef2kt3pvqgwmkbzfr"

Body

application/json

Service + location + window (+ pagination)

serviceId
string
required

The service to find supplier availability for.

Minimum string length: 1
Example:

"srv_01kv60qg12e82acr78edfnjhvv"

offeringId
string
required

The specific offering (variant) of the service being booked.

Minimum string length: 1
Example:

"off_01kv60qge5eh59ap0gw0pqrrys"

locationId
string

Where the service is delivered. Provide this OR both lat and lng. A stored location id (PHYSICAL / VIRTUAL / TRAVEL_ZONE).

Example:

"loc_01kv60qh3m7wznp8s0d2rk9abc"

lat

Client/service latitude. Provide lat + lng together as an alternative to locationId (in-home / travel-zone discovery).

Example:

41.881832

lng

Client/service longitude — see lat.

Example:

-87.623177

durationMinutes
integer

Override the booked duration (minutes). Only honoured for FLEXIBLE offerings; otherwise the offering’s own duration is used.

Required range: x > 0
Example:

60

lookAheadStartDate
string

Start of the search window (ISO-8601). Defaults to now. Slots before this instant are excluded.

Example:

"2025-07-07T00:00:00-05:00"

lookAheadDays
integer

How many days forward to search from the start. Defaults to the engine’s configured window.

Required range: x > 0
Example:

7

timezone
string

IANA timezone governing day bucketing and every *Local field in the response (R-32). Defaults to the project timezone.

Minimum string length: 1
Example:

"America/Chicago"

distanceUnit
enum<string>

Unit for travel/distance calculations.

Available options:
km,
mi
Example:

"km"

interval
integer

Open-slot granularity in minutes (e.g. 15 → :00 / :15 / :30 / :45). Defaults to 15.

Required range: x > 0
Example:

15

language
string

Preferred language for localized skill and offering NAMES. Not a filter — it never affects which suppliers or services match, and has no effect on this response.

Example:

"en"

limit
integer
default:20

Suppliers per page (1–50, default 20). Kept small because each supplier’s availability is computed on demand.

Required range: 1 <= x <= 50
Example:

20

cursor
string

Opaque pagination token from a previous response’s nextCursor. Omit for the first page.

preferredTimes
object[] | null

Time-of-day windows the caller would prefer sessions to fall in (e.g. "after work"). Feeds the per-supplier match score — a supplier with no availability inside these windows is still returned, just ranked lower. Not a filter: no slot is removed for falling outside them.

Example:
daysOfWeek
integer[]

Weekdays the caller would prefer sessions to land on (0 = Sunday … 6 = Saturday). On THIS route this is a ranking preference, not a hard filter — unlike the same-named field on /availability/package-slate, a weekday left out of this list is never removed from a supplier's slots; it only lowers that supplier's match score. At least one weekday is required when this field is present — omit the field entirely for "any day".

Required array length: 1 - 7 elements
Required range: 0 <= x <= 6
Example:
excludeDates
string[]

Local calendar dates (YYYY-MM-DD) that must not carry a session — a holiday, a trip. Matched against each slot's own local calendar date, not against a UTC instant. Pass each date individually; there is no range form.

Maximum array length: 90
Pattern: ^\d{4}-\d{2}-\d{2}$
Example:
sessionsPerWeek
integer

How many sessions per week the caller wants to be able to book with this supplier. On this route there is no package and no session count to plan against, so this preference can only ever feed the match score. On package-slate a package supplies a creditCount, giving the planner an actual COUNT to plan sessions against.

Required range: 1 <= x <= 14
Example:

3

Response

Suppliers, each with open slots grouped by day

searchId
string
required

The id of this search, also returned as the X-MB-Search-Id header. Every page of a paginated search carries the same id (the cursor keeps it). Keep it for the session if you want attribution: pass it back as searchId when the client books, and in the search.rendered event when you report what you showed.

Example:

"srch_01k7q3x9h4e8rb2d6m0z5a7c1n"

data
object[]
required

Suppliers on this page, in a stable order across pages.

timezone
string
required

The IANA timezone actually used for day bucketing and every *Local field (the request timezone, or the project default) — R-32.

Example:

"America/Chicago"

nextCursor
string | null
required

Pass back as cursor to fetch the next page of suppliers. null on the last page.

errors
string[]
required

Non-fatal engine messages. Usually empty.