Search ids
Every search route returns asearchId, in the body and in the
X-MB-Search-Id header:
POST /v1/projects/{projectId}/availability/searchPOST /v1/projects/{projectId}/availability/suppliersPOST /v1/projects/{projectId}/availability/package-slatePOST /v1/projects/{projectId}/availability/package-optionsPOST /v1/projects/{projectId}/availability/time-slotsGET /v1/projects/{projectId}/suppliers
searchId; the cursor keeps
it. Each supplier in the results also carries a 0-based position, continuous
across pages: the first supplier on page 2 is numbered after the last one on
page 1. On POST /availability/search, the suppliers array lists each
supplier that appears in the slots, with its position.
Keep the searchId for the client’s session. You send it back twice: in the
search.rendered event, and in attribution when the client buys.
POST /availability/time-slots returns a searchId too, but nothing from it is
logged for insights: the suppliers and configuration are yours, not the
project’s.
Two optional headers
You can tag any search request with two headers. MarketBox stores them for insights and never acts on them:
Tag health checks and load tests with
monitor or loadtest, so they don’t
count as client demand.
The events
Every event carries:
eventId— your id for the event, a UUID. It’s the idempotency key: a retry that re-sends the same id is counted once.occurredAt— an ISO 8601 instant with an offset orZ. It must be within 24 hours ahead of receipt and 72 hours back.sessionKey— optional. The same opaque key asX-MB-Session-Key, which you can send as a header instead.
Send events from your server
events:write capability. A project admin ticks Site events on the
Application in the dashboard. Standard API access (*) does not include it:
a key without events:write gets a 403 FORBIDDEN. See
Capabilities.
Batch your events: send every 10 seconds or at 500 events, whichever comes
first.
Each event is validated on its own
The answer is always202, with what was accepted and what was not. A rejected
event never fails the batch:
code is one of:
When the whole request fails
The request fails as a whole only on auth, size, shape, rate or an outage:429 or 5xx, retry the same batch with the same eventIds, and
nothing is counted twice. Give up on an event after 72 hours.
Back-filling history. A key that also holds
events:import may send events
up to 400 days old. They are stored as imported.Send events from the browser
navigator.sendBeacon and fetch(…, { keepalive: true }) on a
page that may be closing, so it needs no headers:
- The credential is the publishable key, in
?key=. It is shown on the API Access page beside the API key. It’s public by design — it ships in your page — and can only send events. - Origins are allow-listed. The browser’s
Originmust exactly match one of the origins listed on the Application: scheme and host, exactly as your booking site serves them. Wildcards aren’t accepted. - The body may be
text/plainorapplication/json, so there’s no CORS preflight. - The answer is
204with no body.
413 past either), and about 50 beacons a second per key. Events are
validated exactly as on POST /events, but a rejected event is dropped
silently — the 204 says nothing. Send from your server when you want the
rejections back.
Tie a purchase to its search
When the client buys, sendattribution on
POST /v1/projects/{projectId}/orders:
attribution is optional and stored as given. It is copied onto every booking
the order funds, where you can read it back. A searchId MarketBox never issued
is kept but not counted. Holds and the booking routes don’t take one of their
own.
Privacy
sessionKeyis opaque, and you hash it yourself. Never send an email, an IP address or a user id.- Send a place as a resolution-8 H3 cell (
h3) or aslatandlng. Coordinates are reduced to the cell on receipt and never stored. pathloses its query string on receipt.- Supplier ids must belong to this project.
searchId,listIdandimpressionIdare stored as you sent them.