Skip to main content
POST
Find suppliers + suggested/open slots for a service, location and window

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

serviceId
string
required
Minimum string length: 1
offeringId
string
required
Minimum string length: 1
locationId
string
lat
lng
durationMinutes
integer
Required range: x > 0
lookAheadStartDate
string
lookAheadDays
integer
Required range: x > 0
timezone
string
Minimum string length: 1
distanceUnit
enum<string>
Available options:
km,
mi
order
enum<string> | null
Available options:
mustBeFirst,
mustBeLast,
null
preferredDays
integer[] | null
preferredTimes
object[] | null
emptyDayAnchorTime
string | null
maxNumberOfBookingsPerDay
integer | null
Required range: x > 0
preferredTimeSlotThresholdMins
integer
Required range: x >= 0
timeSuggestionsLimit
integer
Required range: x > 0
sortBy
enum<string>
Available options:
leastTravelTime,
nearestDate
skills
string[]

Supplier skill IDs. A supplier must hold ALL of them to be considered. Omit for no skill filter.

Minimum string length: 1
Example:
interval
integer
Required range: x > 0
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.

bookingType
enum<string>
default:single
Available options:
single,
recurring
rrule
string
endDate
string
daysOfWeek
integer[]
Required range: 0 <= x <= 6
package
boolean
consistencyAsPercentage
boolean
fromMb
boolean

Response

Suggested slots + open slots

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"

status
string
required
timeSlots
null[]
required

Suggested slots, or recurring time patterns when bookingType=recurring. Each entry carries timeSlotDateAndTime (the slot instant rendered in the response timezone, with that zone's offset at that instant — R-30) and timeSlotStartUtc (the same instant in UTC, Z — R-31, always present, always the same instant as timeSlotDateAndTime). Prefer timeSlotStartUtc as the booking anchor.

openSlots
null[]
required

Every free interval at interval granularity, unranked. Each entry carries timeSlotDateAndTime (the slot instant rendered in the response timezone, with that zone's offset at that instant — R-30) and timeSlotStartUtc (the same instant in UTC, Z — R-31, always present, always the same instant as timeSlotDateAndTime). Prefer timeSlotStartUtc as the booking anchor.

suppliers
object[]
required
errors
string[]
required
timezone
string

The IANA timezone actually used to render timeSlotDateAndTime and bucket days (R-32) — the request timezone, or the project default.

Example:

"America/Chicago"

supplierZones
object

IANA profile zone of each supplier that appears in timeSlots/openSlots, keyed by supplierId. Use it as the R-10 fallback for bookingTz on a virtual booking (location zone wins when there is one). Absent key = the supplier has no profile zone; use the project default.

Example:
engineEnabled
boolean

False when Smart Clusters is switched off for this project. The engine then does not run, so timeSlots is empty because it was not computed, not because nobody is free; openSlots is unaffected. Check it before telling a client there is no availability.

Example:

true