Skip to main content
MarketBox runs the search; your site draws the results. Only your site knows which suppliers it actually put on the page, which cards reached the screen, and which ones a client opened. This guide shows how to report that, and how to tie a purchase back to the search it came from. What you report feeds each supplier’s Search insights and Week & demand views, on the dashboard and on the supplier plane.
A search you don’t report counts for nothing. A search with no search.rendered event isn’t counted as Shown, as Seen, or on the demand map.

Search ids

Every search route returns a searchId, in the body and in the X-MB-Search-Id header:
  • POST /v1/projects/{projectId}/availability/search
  • POST /v1/projects/{projectId}/availability/suppliers
  • POST /v1/projects/{projectId}/availability/package-slate
  • POST /v1/projects/{projectId}/availability/package-options
  • POST /v1/projects/{projectId}/availability/time-slots
  • GET /v1/projects/{projectId}/suppliers
Every page of a paginated search carries the same 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 or Z. It must be within 24 hours ahead of receipt and 72 hours back.
  • sessionKey — optional. The same opaque key as X-MB-Session-Key, which you can send as a header instead.

Send events from your server

This is the main path. It takes your API key, which needs the 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 always 202, with what was accepted and what was not. A rejected event never fails the batch:
Fix and resend only the rejected events. A rejection code is one of:

When the whole request fails

The request fails as a whole only on auth, size, shape, rate or an outage:
On a 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

The beacon takes the same events, for sites without a server of their own. It is built for 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 Origin must 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/plain or application/json, so there’s no CORS preflight.
  • The answer is 204 with no body.
Never put your API key in the page. The beacon refuses it with 401, and anyone who reads your page could use it.
The beacon’s limits are tighter: at most 50 events and 64 KB per beacon (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. When the client buys, send attribution 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

  • sessionKey is 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 as lat and lng. Coordinates are reduced to the cell on receipt and never stored.
  • path loses its query string on receipt.
  • Supplier ids must belong to this project. searchId, listId and impressionId are stored as you sent them.

Reference