Report what your site showed: rendered searches, lists, impressions, clicks, profile views
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, so it reports them here and each supplier sees them in their Search insights. Send from your server, batched: every 10 seconds or at 500 events, whichever comes first. The API key needs the events:write capability, granted by name on the application in the dashboard (a key without it — including a legacy key or a * key — gets 403).
Event types.search.rendered: the results of a MarketBox search were drawn (carry its searchId and the supplier ids drawn, in order, with their 0-based position). This is what makes a search count: a search with no render counts for nothing, not as Shown, not as Seen, not on the demand map. opportunity: any list that includes suppliers was drawn (home page, a city page, a widget), one per list render; an opportunity carrying a searchId counts as the render too. impression: a supplier’s card was at least 50 % in the viewport for the first time in that list (IntersectionObserver, threshold 0.5); carries the opportunity’s eventId as listId. click: the client opened a profile or card from a list; carries impressionId (or listId + supplierId when you do not track impressions). profile_view: a profile page loaded, from anywhere. coverage_miss: a client entered an address and your site found nobody without calling a MarketBox search.
Each event is validated on its own. The response is always 202 with accepted and the rejected ones by index and code; a rejected event never fails the batch. The whole request fails only on auth (401/403), size (413: over 256 KB) or shape (400: no events, or over 500). eventId is your idempotency key: on a 429 or 5xx retry the same batch with the same ids and nothing is counted twice. occurredAt must be within 24 hours ahead and 72 hours back of receipt; a key holding events:import may send up to 400 days back (a back-fill), and those events are stored as imported. Give up on an event after 72 hours.
Privacy.sessionKey is opaque and hashed by you — never an email, IP or user id. A place is sent as a resolution-8 H3 cell or as lat/lng; coordinates are reduced to the cell on receipt and never stored. path loses its query string. Supplier ids must belong to this project; searchId, listId and impressionId are stored as you sent them.
About 50 requests a second per key are allowed, with bursts of 100; past that a 429 with Retry-After.
POST
/
v1
/
projects
/
{projectId}
/
events
Report what your site showed: rendered searches, lists, impressions, clicks, profile views
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.
Headers
x-mb-session-key
string
Default sessionKey for every event in the batch that has none: an opaque per-session key you hash yourself, at most 64 characters. A longer value is ignored, never an error.
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
The batch of events
events
object[]
required
The events, at most 500 per request (and 256 KB in all). Each is validated on its own.
Required array length: 1 - 500 elements
One site event. type picks the shape: opportunity, impression, click, profile_view, coverage_miss or search.rendered. An element that does not match its shape is rejected on its own in the 202 body, never the whole batch.
The batch was read: what was accepted and what was not
accepted
integer
required
Events accepted and recorded. accepted + rejected.length is the number sent. When nothing could be recorded the answer is 503, not 202, so retry on it.
Example:
41
duplicates
integer
required
Always 0 for now. A repeated eventId is accepted and counted once by the rollup, so a retry never double-counts; this field will report what the rollup collapsed.
Example:
0
rejected
object[]
required
The events not accepted, in batch order. Fix and resend only these.
Show child attributes
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"MarketBox API","description":"Reference and guides for the MarketBox public API","colors":{"primary":"#0087EE","light":"#0087EE","dark":"#0087EE"},"logo":{"light":"https://mintcdn.com/marketboxinc/ajdEqdrEaJkvfx4T/logo/light.svg?fit=max\u0026auto=format\u0026n=ajdEqdrEaJkvfx4T\u0026q=85\u0026s=655948ee6454a1e06bfe0dffda47c7cc","dark":"https://mintcdn.com/marketboxinc/ajdEqdrEaJkvfx4T/logo/dark.svg?fit=max\u0026auto=format\u0026n=ajdEqdrEaJkvfx4T\u0026q=85\u0026s=54826a391e30ee9c27adf963d88a61eb"},"favicon":"https://mintcdn.com/marketboxinc/oL3tvBLJ_yQtNXOS/favicon.svg?fit=max\u0026auto=format\u0026n=oL3tvBLJ_yQtNXOS\u0026q=85\u0026s=01ed3064e8e10cbf6c9a05fae050a805","navbar":{"primary":{"type":"button","label":"Dashboard","href":"https://app.gomarketbox.com/dashboard"}},"footer":{"socials":{"x":"https://x.com/marketboxio","linkedin":"https://linkedin.com/company/marketbox"}},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"marketboxinc","hasAudioNarration":false,"actualSubdomain":"marketboxinc","customDomains":["docs.gomarketbox.com"],"gitSource":{"type":"github","owner":"gomarketbox","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6aff115945eb182701d43e97","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"API reference","count":139},{"language":"default","tag":"Endpoints","count":138},{"language":"default","tag":"Guides","count":89},{"language":"default","tag":"Supplier plane","count":38},{"language":"default","tag":"Bookings","count":20},{"language":"default","tag":"Core concepts","count":14},{"language":"default","tag":"Orders","count":13},{"language":"default","tag":"Resources","count":12},{"language":"default","tag":"Suppliers","count":12},{"language":"default","tag":"Build a supplier portal","count":9}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[]}
{"page":{"pagePath":"api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views","slug":"/api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views","pageMetadata":{"title":"Report what your site showed: rendered searches, lists, impressions, clicks, profile views","description":"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, so it reports them here and each supplier sees them in their Search insights. Send from your server, batched: every 10 seconds or at 500 events, whichever comes first. The API key needs the `events:write` capability, granted by name on the application in the dashboard (a key without it — including a legacy key or a `*` key — gets 403).\n\n**Event types.** `search.rendered`: the results of a MarketBox search were drawn (carry its `searchId` and the supplier ids drawn, in order, with their 0-based `position`). **This is what makes a search count**: a search with no render counts for nothing, not as Shown, not as Seen, not on the demand map. `opportunity`: any list that includes suppliers was drawn (home page, a city page, a widget), one per list render; an opportunity carrying a `searchId` counts as the render too. `impression`: a supplier's card was at least 50 % in the viewport for the first time in that list (`IntersectionObserver`, threshold 0.5); carries the opportunity's `eventId` as `listId`. `click`: the client opened a profile or card from a list; carries `impressionId` (or `listId` + `supplierId` when you do not track impressions). `profile_view`: a profile page loaded, from anywhere. `coverage_miss`: a client entered an address and your site found nobody without calling a MarketBox search.\n\n**Each event is validated on its own.** The response is always 202 with `accepted` and the `rejected` ones by index and code; a rejected event never fails the batch. The whole request fails only on auth (401/403), size (413: over 256 KB) or shape (400: no `events`, or over 500). `eventId` is your idempotency key: on a 429 or 5xx retry the same batch with the same ids and nothing is counted twice. `occurredAt` must be within 24 hours ahead and 72 hours back of receipt; a key holding `events:import` may send up to 400 days back (a back-fill), and those events are stored as imported. Give up on an event after 72 hours.\n\n**Privacy.** `sessionKey` is opaque and hashed by you — never an email, IP or user id. A place is sent as a resolution-8 H3 cell or as `lat`/`lng`; coordinates are reduced to the cell on receipt and never stored. `path` loses its query string. Supplier ids must belong to this project; `searchId`, `listId` and `impressionId` are stored as you sent them.\n\nAbout 50 requests a second per key are allowed, with bursts of 100; past that a 429 with `Retry-After`.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/events","href":"/api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n strong: \"strong\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"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, so it reports them here and each supplier sees them in their Search insights. Send from your server, batched: every 10 seconds or at 500 events, whichever comes first. The API key needs the \", _jsx(_components.code, {\n children: \"events:write\"\n }), \" capability, granted by name on the application in the dashboard (a key without it — including a legacy key or a \", _jsx(_components.code, {\n children: \"*\"\n }), \" key — gets 403).\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Event types.\"\n }), \" \", _jsx(_components.code, {\n children: \"search.rendered\"\n }), \": the results of a MarketBox search were drawn (carry its \", _jsx(_components.code, {\n children: \"searchId\"\n }), \" and the supplier ids drawn, in order, with their 0-based \", _jsx(_components.code, {\n children: \"position\"\n }), \"). \", _jsx(_components.strong, {\n children: \"This is what makes a search count\"\n }), \": a search with no render counts for nothing, not as Shown, not as Seen, not on the demand map. \", _jsx(_components.code, {\n children: \"opportunity\"\n }), \": any list that includes suppliers was drawn (home page, a city page, a widget), one per list render; an opportunity carrying a \", _jsx(_components.code, {\n children: \"searchId\"\n }), \" counts as the render too. \", _jsx(_components.code, {\n children: \"impression\"\n }), \": a supplier’s card was at least 50 % in the viewport for the first time in that list (\", _jsx(_components.code, {\n children: \"IntersectionObserver\"\n }), \", threshold 0.5); carries the opportunity’s \", _jsx(_components.code, {\n children: \"eventId\"\n }), \" as \", _jsx(_components.code, {\n children: \"listId\"\n }), \". \", _jsx(_components.code, {\n children: \"click\"\n }), \": the client opened a profile or card from a list; carries \", _jsx(_components.code, {\n children: \"impressionId\"\n }), \" (or \", _jsx(_components.code, {\n children: \"listId\"\n }), \" + \", _jsx(_components.code, {\n children: \"supplierId\"\n }), \" when you do not track impressions). \", _jsx(_components.code, {\n children: \"profile_view\"\n }), \": a profile page loaded, from anywhere. \", _jsx(_components.code, {\n children: \"coverage_miss\"\n }), \": a client entered an address and your site found nobody without calling a MarketBox search.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Each event is validated on its own.\"\n }), \" The response is always 202 with \", _jsx(_components.code, {\n children: \"accepted\"\n }), \" and the \", _jsx(_components.code, {\n children: \"rejected\"\n }), \" ones by index and code; a rejected event never fails the batch. The whole request fails only on auth (401/403), size (413: over 256 KB) or shape (400: no \", _jsx(_components.code, {\n children: \"events\"\n }), \", or over 500). \", _jsx(_components.code, {\n children: \"eventId\"\n }), \" is your idempotency key: on a 429 or 5xx retry the same batch with the same ids and nothing is counted twice. \", _jsx(_components.code, {\n children: \"occurredAt\"\n }), \" must be within 24 hours ahead and 72 hours back of receipt; a key holding \", _jsx(_components.code, {\n children: \"events:import\"\n }), \" may send up to 400 days back (a back-fill), and those events are stored as imported. Give up on an event after 72 hours.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Privacy.\"\n }), \" \", _jsx(_components.code, {\n children: \"sessionKey\"\n }), \" is opaque and hashed by you — never an email, IP or user id. A place is sent as a resolution-8 H3 cell or as \", _jsx(_components.code, {\n children: \"lat\"\n }), \"/\", _jsx(_components.code, {\n children: \"lng\"\n }), \"; coordinates are reduced to the cell on receipt and never stored. \", _jsx(_components.code, {\n children: \"path\"\n }), \" loses its query string. Supplier ids must belong to this project; \", _jsx(_components.code, {\n children: \"searchId\"\n }), \", \", _jsx(_components.code, {\n children: \"listId\"\n }), \" and \", _jsx(_components.code, {\n children: \"impressionId\"\n }), \" are stored as you sent them.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"About 50 requests a second per key are allowed, with bursts of 100; past that a 429 with \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \".\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Report what your site showed: rendered searches, lists, impressions, clicks, profile views","description":"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, so it reports them here and each supplier sees them in their Search insights. Send from your server, batched: every 10 seconds or at 500 events, whichever comes first. The API key needs the `events:write` capability, granted by name on the application in the dashboard (a key without it — including a legacy key or a `*` key — gets 403).\n\n**Event types.** `search.rendered`: the results of a MarketBox search were drawn (carry its `searchId` and the supplier ids drawn, in order, with their 0-based `position`). **This is what makes a search count**: a search with no render counts for nothing, not as Shown, not as Seen, not on the demand map. `opportunity`: any list that includes suppliers was drawn (home page, a city page, a widget), one per list render; an opportunity carrying a `searchId` counts as the render too. `impression`: a supplier's card was at least 50 % in the viewport for the first time in that list (`IntersectionObserver`, threshold 0.5); carries the opportunity's `eventId` as `listId`. `click`: the client opened a profile or card from a list; carries `impressionId` (or `listId` + `supplierId` when you do not track impressions). `profile_view`: a profile page loaded, from anywhere. `coverage_miss`: a client entered an address and your site found nobody without calling a MarketBox search.\n\n**Each event is validated on its own.** The response is always 202 with `accepted` and the `rejected` ones by index and code; a rejected event never fails the batch. The whole request fails only on auth (401/403), size (413: over 256 KB) or shape (400: no `events`, or over 500). `eventId` is your idempotency key: on a 429 or 5xx retry the same batch with the same ids and nothing is counted twice. `occurredAt` must be within 24 hours ahead and 72 hours back of receipt; a key holding `events:import` may send up to 400 days back (a back-fill), and those events are stored as imported. Give up on an event after 72 hours.\n\n**Privacy.** `sessionKey` is opaque and hashed by you — never an email, IP or user id. A place is sent as a resolution-8 H3 cell or as `lat`/`lng`; coordinates are reduced to the cell on receipt and never stored. `path` loses its query string. Supplier ids must belong to this project; `searchId`, `listId` and `impressionId` are stored as you sent them.\n\nAbout 50 requests a second per key are allowed, with bursts of 100; past that a 429 with `Retry-After`.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/events","href":"/api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["Events"],"summary":"Report what your site showed: rendered searches, lists, impressions, clicks, profile views","description":"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, so it reports them here and each supplier sees them in their Search insights. Send from your server, batched: every 10 seconds or at 500 events, whichever comes first. The API key needs the `events:write` capability, granted by name on the application in the dashboard (a key without it — including a legacy key or a `*` key — gets 403).\n\n**Event types.** `search.rendered`: the results of a MarketBox search were drawn (carry its `searchId` and the supplier ids drawn, in order, with their 0-based `position`). **This is what makes a search count**: a search with no render counts for nothing, not as Shown, not as Seen, not on the demand map. `opportunity`: any list that includes suppliers was drawn (home page, a city page, a widget), one per list render; an opportunity carrying a `searchId` counts as the render too. `impression`: a supplier's card was at least 50 % in the viewport for the first time in that list (`IntersectionObserver`, threshold 0.5); carries the opportunity's `eventId` as `listId`. `click`: the client opened a profile or card from a list; carries `impressionId` (or `listId` + `supplierId` when you do not track impressions). `profile_view`: a profile page loaded, from anywhere. `coverage_miss`: a client entered an address and your site found nobody without calling a MarketBox search.\n\n**Each event is validated on its own.** The response is always 202 with `accepted` and the `rejected` ones by index and code; a rejected event never fails the batch. The whole request fails only on auth (401/403), size (413: over 256 KB) or shape (400: no `events`, or over 500). `eventId` is your idempotency key: on a 429 or 5xx retry the same batch with the same ids and nothing is counted twice. `occurredAt` must be within 24 hours ahead and 72 hours back of receipt; a key holding `events:import` may send up to 400 days back (a back-fill), and those events are stored as imported. Give up on an event after 72 hours.\n\n**Privacy.** `sessionKey` is opaque and hashed by you — never an email, IP or user id. A place is sent as a resolution-8 H3 cell or as `lat`/`lng`; coordinates are reduced to the cell on receipt and never stored. `path` loses its query string. Supplier ids must belong to this project; `searchId`, `listId` and `impressionId` are stored as you sent them.\n\nAbout 50 requests a second per key are allowed, with bursts of 100; past that a 429 with `Retry-After`.","parameters":["2c6d5889-4a66-4c93-9834-739039d9d4af","f3b732d4-544e-4917-ad89-af589f7810d5"],"requestBody":"1a64826a-bb56-42c1-b866-c03127c3ae6e","responses":{"202":"aceb59cd-173e-4768-a7b8-ac8576b11b4e","400":"25e62a27-d2a6-4640-92f8-31e33a2f57ee","401":"435338be-0909-42fb-b233-87604dc3a7be","403":"f9c531d6-99ef-4fdc-bd68-504bda71aeaa","413":"11cfe359-af53-4e8b-a260-7344311065e4","429":"5f5640ec-b2f1-4b31-ab4e-d209e1ff5729","503":"31984ec8-f038-4d09-a2f2-3e67a41d0200"},"method":"post","type":"path","servers":["7f0c0cfd-7cba-4616-861f-ca7611ae4010"],"security":["db6d1cf6-4a08-4a4c-92da-023445e576e6"],"path":"/v1/projects/{projectId}/events","baseUrlOptions":["https://apiv2.gomarketbox.com"],"title":"Report what your site showed: rendered searches, lists, impressions, clicks, profile views","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"2c6d5889-4a66-4c93-9834-739039d9d4af":{"schema":{"type":"string","minLength":1,"description":"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.","example":"prj_01kv60qgnef2kt3pvqgwmkbzfr","isRequired":true,"uniqueKey":"","typeLabel":"string"},"required":true,"description":"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.","name":"projectId","in":"path"},"f3b732d4-544e-4917-ad89-af589f7810d5":{"schema":{"type":"string","description":"Default `sessionKey` for every event in the batch that has none: an opaque per-session key you hash yourself, at most 64 characters. A longer value is ignored, never an error.","isRequired":false,"uniqueKey":"","typeLabel":"string"},"required":false,"description":"Default `sessionKey` for every event in the batch that has none: an opaque per-session key you hash yourself, at most 64 characters. A longer value is ignored, never an error.","name":"x-mb-session-key","in":"header"}},"requestBody":{"description":"The batch of events","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"oneOf":[{"type":"object","description":"One site event. `type` picks the shape: `opportunity`, `impression`, `click`, `profile_view`, `coverage_miss` or `search.rendered`. An element that does not match its shape is rejected on its own in the 202 body, never the whole batch.","required":["type","eventId","occurredAt","surface","suppliers"],"properties":{"type":{"type":"string","enum":["opportunity"],"example":"opportunity","description":"A list that includes suppliers was drawn: one event per list render.","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.0.type","typeLabel":"enum\u003cstring>"},"eventId":{"type":"string","minLength":1,"maxLength":128,"description":"Your id for this event — a UUID (v4 or v7), unique within the project. The idempotency key: a retry re-sending the same id is accepted and counted once.","example":"lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.0.eventId","typeLabel":"string"},"occurredAt":{"type":"string","format":"date-time","description":"When it happened, as an ISO 8601 instant with an offset or `Z` (R-1). Rejected per event when more than 24 hours ahead of receipt, or older than 72 hours without the `events:import` capability (400 days with it).","example":"2026-10-03T14:05:10.020Z","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.0.occurredAt","typeLabel":"string\u003cdate-time>"},"surface":{"type":"string","enum":["home","results","listing","site_search","profile","widget","assistant","other"],"description":"Where on the site the list was drawn.","example":"results","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.0.surface","typeLabel":"enum\u003cstring>"},"suppliers":{"type":"array","items":{"type":"object","properties":{"supplierId":{"type":"string","minLength":1,"maxLength":128,"description":"The MarketBox supplier id. Must belong to this project, or the event is rejected.","example":"sup_01kv60qh3m7wznp8s0d2rk9abc","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.0.suppliers.items.[INDEX].supplierId","typeLabel":"string"},"position":{"type":"integer","minimum":0,"description":"0-based rank in the list as drawn (the same number a search response returns).","example":0,"isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.0.suppliers.items.[INDEX].position","typeLabel":"integer"}},"required":["supplierId","position"],"additionalProperties":false,"uniqueKey":"events.items.[INDEX].oneOf.0.suppliers.items.[INDEX]","typeLabel":"object"},"maxItems":100,"description":"The suppliers actually put on the page, in the order drawn, at most 100. Every id must belong to this project, or the whole event is rejected.","example":[{"supplierId":"sup_01kv60qh3m7wznp8s0d2rk9abc","position":0},{"supplierId":"sup_01kv60qh3m7wznp8s0d2rk9def","position":1}],"isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.0.suppliers","typeLabel":"object[]"},"sessionKey":{"type":"string","minLength":1,"maxLength":64,"description":"An opaque per-session key you hash yourself, at most 64 characters. Never an email, IP or user id. Alternatively the `X-MB-Session-Key` header.","example":"sess-example-01","uniqueKey":"events.items.[INDEX].oneOf.0.sessionKey","typeLabel":"string"},"searchId":{"type":"string","minLength":1,"maxLength":128,"description":"The `searchId` of the MarketBox search response the list came from, when it did (the `X-MB-Search-Id` header / body field of every search route).","example":"srch_01k7q3x9h4e8rb2d6m0z5a7c1n","uniqueKey":"events.items.[INDEX].oneOf.0.searchId","typeLabel":"string"},"path":{"type":"string","maxLength":300,"description":"The page path, at most 300 characters. The query string is stripped on receipt.","example":"/en-ca/book/results","uniqueKey":"events.items.[INDEX].oneOf.0.path","typeLabel":"string"},"serviceId":{"type":"string","minLength":1,"maxLength":128,"description":"The service the list or search was for, when there was one.","example":"srv_01kv60qg12e82acr78edfnjhvv","uniqueKey":"events.items.[INDEX].oneOf.0.serviceId","typeLabel":"string"},"locale":{"type":"string","minLength":2,"maxLength":16,"description":"The page locale, as a BCP 47 tag.","example":"en-CA","uniqueKey":"events.items.[INDEX].oneOf.0.locale","typeLabel":"string"},"h3":{"type":"string","pattern":"^88[0-9a-f]{13}$","description":"The place in the event as a resolution-8 H3 cell. Send this or `lat`/`lng`, not both.","example":"882b8e4a0dfffff","uniqueKey":"events.items.[INDEX].oneOf.0.h3","typeLabel":"string"},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.","example":43.6532,"uniqueKey":"events.items.[INDEX].oneOf.0.lat","typeLabel":"number"},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.","example":-79.3832,"uniqueKey":"events.items.[INDEX].oneOf.0.lng","typeLabel":"number"}},"additionalProperties":false,"uniqueKey":"events.items.[INDEX].oneOf.0","typeLabel":"object"},{"type":"object","description":"One site event. `type` picks the shape: `opportunity`, `impression`, `click`, `profile_view`, `coverage_miss` or `search.rendered`. An element that does not match its shape is rejected on its own in the 202 body, never the whole batch.","required":["type","eventId","occurredAt","listId","supplierId","position"],"properties":{"type":{"type":"string","enum":["impression"],"example":"impression","description":"A supplier's card reached the screen (≥ 50 % in the viewport) for the first time in that list render.","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.1.type","typeLabel":"enum\u003cstring>"},"eventId":{"type":"string","minLength":1,"maxLength":128,"description":"Your id for this event — a UUID (v4 or v7), unique within the project. The idempotency key: a retry re-sending the same id is accepted and counted once.","example":"lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.1.eventId","typeLabel":"string"},"occurredAt":{"type":"string","format":"date-time","description":"When it happened, as an ISO 8601 instant with an offset or `Z` (R-1). Rejected per event when more than 24 hours ahead of receipt, or older than 72 hours without the `events:import` capability (400 days with it).","example":"2026-10-03T14:05:10.020Z","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.1.occurredAt","typeLabel":"string\u003cdate-time>"},"listId":{"type":"string","minLength":1,"maxLength":128,"description":"The `eventId` of the `opportunity` this card belongs to.","example":"lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.1.listId","typeLabel":"string"},"supplierId":{"type":"string","minLength":1,"maxLength":128,"description":"The MarketBox supplier id. Must belong to this project, or the event is rejected.","example":"sup_01kv60qh3m7wznp8s0d2rk9abc","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.1.supplierId","typeLabel":"string"},"position":{"type":"integer","minimum":0,"description":"0-based rank in the list as drawn (the same number a search response returns).","example":0,"isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.1.position","typeLabel":"integer"},"sessionKey":{"type":"string","minLength":1,"maxLength":64,"description":"An opaque per-session key you hash yourself, at most 64 characters. Never an email, IP or user id. Alternatively the `X-MB-Session-Key` header.","example":"sess-example-01","uniqueKey":"events.items.[INDEX].oneOf.1.sessionKey","typeLabel":"string"},"searchId":{"type":"string","minLength":1,"maxLength":128,"description":"The `searchId` of the MarketBox search response the list came from, when it did (the `X-MB-Search-Id` header / body field of every search route).","example":"srch_01k7q3x9h4e8rb2d6m0z5a7c1n","uniqueKey":"events.items.[INDEX].oneOf.1.searchId","typeLabel":"string"},"path":{"type":"string","maxLength":300,"description":"The page path, at most 300 characters. The query string is stripped on receipt.","example":"/en-ca/book/results","uniqueKey":"events.items.[INDEX].oneOf.1.path","typeLabel":"string"},"serviceId":{"type":"string","minLength":1,"maxLength":128,"description":"The service the list or search was for, when there was one.","example":"srv_01kv60qg12e82acr78edfnjhvv","uniqueKey":"events.items.[INDEX].oneOf.1.serviceId","typeLabel":"string"},"locale":{"type":"string","minLength":2,"maxLength":16,"description":"The page locale, as a BCP 47 tag.","example":"en-CA","uniqueKey":"events.items.[INDEX].oneOf.1.locale","typeLabel":"string"},"h3":{"type":"string","pattern":"^88[0-9a-f]{13}$","description":"The place in the event as a resolution-8 H3 cell. Send this or `lat`/`lng`, not both.","example":"882b8e4a0dfffff","uniqueKey":"events.items.[INDEX].oneOf.1.h3","typeLabel":"string"},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.","example":43.6532,"uniqueKey":"events.items.[INDEX].oneOf.1.lat","typeLabel":"number"},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.","example":-79.3832,"uniqueKey":"events.items.[INDEX].oneOf.1.lng","typeLabel":"number"}},"additionalProperties":false,"uniqueKey":"events.items.[INDEX].oneOf.1","typeLabel":"object"},{"type":"object","description":"One site event. `type` picks the shape: `opportunity`, `impression`, `click`, `profile_view`, `coverage_miss` or `search.rendered`. An element that does not match its shape is rejected on its own in the 202 body, never the whole batch.","required":["type","eventId","occurredAt","supplierId"],"properties":{"type":{"type":"string","enum":["click"],"example":"click","description":"The client opened a supplier's profile or card from a list.","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.2.type","typeLabel":"enum\u003cstring>"},"eventId":{"type":"string","minLength":1,"maxLength":128,"description":"Your id for this event — a UUID (v4 or v7), unique within the project. The idempotency key: a retry re-sending the same id is accepted and counted once.","example":"lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.2.eventId","typeLabel":"string"},"occurredAt":{"type":"string","format":"date-time","description":"When it happened, as an ISO 8601 instant with an offset or `Z` (R-1). Rejected per event when more than 24 hours ahead of receipt, or older than 72 hours without the `events:import` capability (400 days with it).","example":"2026-10-03T14:05:10.020Z","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.2.occurredAt","typeLabel":"string\u003cdate-time>"},"supplierId":{"type":"string","minLength":1,"maxLength":128,"description":"The MarketBox supplier id. Must belong to this project, or the event is rejected.","example":"sup_01kv60qh3m7wznp8s0d2rk9abc","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.2.supplierId","typeLabel":"string"},"sessionKey":{"type":"string","minLength":1,"maxLength":64,"description":"An opaque per-session key you hash yourself, at most 64 characters. Never an email, IP or user id. Alternatively the `X-MB-Session-Key` header.","example":"sess-example-01","uniqueKey":"events.items.[INDEX].oneOf.2.sessionKey","typeLabel":"string"},"searchId":{"type":"string","minLength":1,"maxLength":128,"description":"The `searchId` of the MarketBox search response the list came from, when it did (the `X-MB-Search-Id` header / body field of every search route).","example":"srch_01k7q3x9h4e8rb2d6m0z5a7c1n","uniqueKey":"events.items.[INDEX].oneOf.2.searchId","typeLabel":"string"},"path":{"type":"string","maxLength":300,"description":"The page path, at most 300 characters. The query string is stripped on receipt.","example":"/en-ca/book/results","uniqueKey":"events.items.[INDEX].oneOf.2.path","typeLabel":"string"},"serviceId":{"type":"string","minLength":1,"maxLength":128,"description":"The service the list or search was for, when there was one.","example":"srv_01kv60qg12e82acr78edfnjhvv","uniqueKey":"events.items.[INDEX].oneOf.2.serviceId","typeLabel":"string"},"locale":{"type":"string","minLength":2,"maxLength":16,"description":"The page locale, as a BCP 47 tag.","example":"en-CA","uniqueKey":"events.items.[INDEX].oneOf.2.locale","typeLabel":"string"},"h3":{"type":"string","pattern":"^88[0-9a-f]{13}$","description":"The place in the event as a resolution-8 H3 cell. Send this or `lat`/`lng`, not both.","example":"882b8e4a0dfffff","uniqueKey":"events.items.[INDEX].oneOf.2.h3","typeLabel":"string"},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.","example":43.6532,"uniqueKey":"events.items.[INDEX].oneOf.2.lat","typeLabel":"number"},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.","example":-79.3832,"uniqueKey":"events.items.[INDEX].oneOf.2.lng","typeLabel":"number"},"impressionId":{"type":"string","minLength":1,"maxLength":128,"description":"The `eventId` of the `impression` that was clicked. Send this, or `listId` when you do not track impressions.","example":"imp_2b7e1d5c-9f4a-4b8e-a3c6-7d0e2f1a9b4c","uniqueKey":"events.items.[INDEX].oneOf.2.impressionId","typeLabel":"string"},"listId":{"type":"string","minLength":1,"maxLength":128,"description":"The `eventId` of the `opportunity` the card was in, when no `impressionId` is known.","example":"lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b","uniqueKey":"events.items.[INDEX].oneOf.2.listId","typeLabel":"string"}},"additionalProperties":false,"uniqueKey":"events.items.[INDEX].oneOf.2","typeLabel":"object"},{"type":"object","description":"One site event. `type` picks the shape: `opportunity`, `impression`, `click`, `profile_view`, `coverage_miss` or `search.rendered`. An element that does not match its shape is rejected on its own in the 202 body, never the whole batch.","required":["type","eventId","occurredAt","supplierId","referrerClass"],"properties":{"type":{"type":"string","enum":["profile_view"],"example":"profile_view","description":"A supplier's profile page loaded, from anywhere.","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.3.type","typeLabel":"enum\u003cstring>"},"eventId":{"type":"string","minLength":1,"maxLength":128,"description":"Your id for this event — a UUID (v4 or v7), unique within the project. The idempotency key: a retry re-sending the same id is accepted and counted once.","example":"lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.3.eventId","typeLabel":"string"},"occurredAt":{"type":"string","format":"date-time","description":"When it happened, as an ISO 8601 instant with an offset or `Z` (R-1). Rejected per event when more than 24 hours ahead of receipt, or older than 72 hours without the `events:import` capability (400 days with it).","example":"2026-10-03T14:05:10.020Z","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.3.occurredAt","typeLabel":"string\u003cdate-time>"},"supplierId":{"type":"string","minLength":1,"maxLength":128,"description":"The MarketBox supplier id. Must belong to this project, or the event is rejected.","example":"sup_01kv60qh3m7wznp8s0d2rk9abc","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.3.supplierId","typeLabel":"string"},"referrerClass":{"type":"string","enum":["internal","search","direct","social","ads","other_site","assistant"],"description":"How the visitor reached the profile page: from your own site, a search engine, a typed URL, a social network, an ad, another site, or an AI assistant.","example":"internal","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.3.referrerClass","typeLabel":"enum\u003cstring>"},"sessionKey":{"type":"string","minLength":1,"maxLength":64,"description":"An opaque per-session key you hash yourself, at most 64 characters. Never an email, IP or user id. Alternatively the `X-MB-Session-Key` header.","example":"sess-example-01","uniqueKey":"events.items.[INDEX].oneOf.3.sessionKey","typeLabel":"string"},"searchId":{"type":"string","minLength":1,"maxLength":128,"description":"The `searchId` of the MarketBox search response the list came from, when it did (the `X-MB-Search-Id` header / body field of every search route).","example":"srch_01k7q3x9h4e8rb2d6m0z5a7c1n","uniqueKey":"events.items.[INDEX].oneOf.3.searchId","typeLabel":"string"},"path":{"type":"string","maxLength":300,"description":"The page path, at most 300 characters. The query string is stripped on receipt.","example":"/en-ca/book/results","uniqueKey":"events.items.[INDEX].oneOf.3.path","typeLabel":"string"},"serviceId":{"type":"string","minLength":1,"maxLength":128,"description":"The service the list or search was for, when there was one.","example":"srv_01kv60qg12e82acr78edfnjhvv","uniqueKey":"events.items.[INDEX].oneOf.3.serviceId","typeLabel":"string"},"locale":{"type":"string","minLength":2,"maxLength":16,"description":"The page locale, as a BCP 47 tag.","example":"en-CA","uniqueKey":"events.items.[INDEX].oneOf.3.locale","typeLabel":"string"},"h3":{"type":"string","pattern":"^88[0-9a-f]{13}$","description":"The place in the event as a resolution-8 H3 cell. Send this or `lat`/`lng`, not both.","example":"882b8e4a0dfffff","uniqueKey":"events.items.[INDEX].oneOf.3.h3","typeLabel":"string"},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.","example":43.6532,"uniqueKey":"events.items.[INDEX].oneOf.3.lat","typeLabel":"number"},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.","example":-79.3832,"uniqueKey":"events.items.[INDEX].oneOf.3.lng","typeLabel":"number"}},"additionalProperties":false,"uniqueKey":"events.items.[INDEX].oneOf.3","typeLabel":"object"},{"type":"object","description":"One site event. `type` picks the shape: `opportunity`, `impression`, `click`, `profile_view`, `coverage_miss` or `search.rendered`. An element that does not match its shape is rejected on its own in the 202 body, never the whole batch.","required":["type","eventId","occurredAt"],"properties":{"type":{"type":"string","enum":["coverage_miss"],"example":"coverage_miss","description":"A client entered an address and the site found nobody, without calling a MarketBox search.","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.4.type","typeLabel":"enum\u003cstring>"},"eventId":{"type":"string","minLength":1,"maxLength":128,"description":"Your id for this event — a UUID (v4 or v7), unique within the project. The idempotency key: a retry re-sending the same id is accepted and counted once.","example":"lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.4.eventId","typeLabel":"string"},"occurredAt":{"type":"string","format":"date-time","description":"When it happened, as an ISO 8601 instant with an offset or `Z` (R-1). Rejected per event when more than 24 hours ahead of receipt, or older than 72 hours without the `events:import` capability (400 days with it).","example":"2026-10-03T14:05:10.020Z","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.4.occurredAt","typeLabel":"string\u003cdate-time>"},"sessionKey":{"type":"string","minLength":1,"maxLength":64,"description":"An opaque per-session key you hash yourself, at most 64 characters. Never an email, IP or user id. Alternatively the `X-MB-Session-Key` header.","example":"sess-example-01","uniqueKey":"events.items.[INDEX].oneOf.4.sessionKey","typeLabel":"string"},"searchId":{"type":"string","minLength":1,"maxLength":128,"description":"The `searchId` of the MarketBox search response the list came from, when it did (the `X-MB-Search-Id` header / body field of every search route).","example":"srch_01k7q3x9h4e8rb2d6m0z5a7c1n","uniqueKey":"events.items.[INDEX].oneOf.4.searchId","typeLabel":"string"},"path":{"type":"string","maxLength":300,"description":"The page path, at most 300 characters. The query string is stripped on receipt.","example":"/en-ca/book/results","uniqueKey":"events.items.[INDEX].oneOf.4.path","typeLabel":"string"},"serviceId":{"type":"string","minLength":1,"maxLength":128,"description":"The service the list or search was for, when there was one.","example":"srv_01kv60qg12e82acr78edfnjhvv","uniqueKey":"events.items.[INDEX].oneOf.4.serviceId","typeLabel":"string"},"locale":{"type":"string","minLength":2,"maxLength":16,"description":"The page locale, as a BCP 47 tag.","example":"en-CA","uniqueKey":"events.items.[INDEX].oneOf.4.locale","typeLabel":"string"},"h3":{"type":"string","pattern":"^88[0-9a-f]{13}$","description":"The place in the event as a resolution-8 H3 cell. Send this or `lat`/`lng`, not both.","example":"882b8e4a0dfffff","uniqueKey":"events.items.[INDEX].oneOf.4.h3","typeLabel":"string"},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.","example":43.6532,"uniqueKey":"events.items.[INDEX].oneOf.4.lat","typeLabel":"number"},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.","example":-79.3832,"uniqueKey":"events.items.[INDEX].oneOf.4.lng","typeLabel":"number"}},"additionalProperties":false,"uniqueKey":"events.items.[INDEX].oneOf.4","typeLabel":"object"},{"type":"object","description":"One site event. `type` picks the shape: `opportunity`, `impression`, `click`, `profile_view`, `coverage_miss` or `search.rendered`. An element that does not match its shape is rejected on its own in the 202 body, never the whole batch.","required":["type","eventId","occurredAt","searchId","surface","suppliers"],"properties":{"type":{"type":"string","enum":["search.rendered"],"example":"search.rendered","description":"The results of a MarketBox search were drawn. This is what makes a search count: a search with no render counts for nothing. A later page drawn is another event with the same `searchId`.","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.5.type","typeLabel":"enum\u003cstring>"},"eventId":{"type":"string","minLength":1,"maxLength":128,"description":"Your id for this event — a UUID (v4 or v7), unique within the project. The idempotency key: a retry re-sending the same id is accepted and counted once.","example":"lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.5.eventId","typeLabel":"string"},"occurredAt":{"type":"string","format":"date-time","description":"When it happened, as an ISO 8601 instant with an offset or `Z` (R-1). Rejected per event when more than 24 hours ahead of receipt, or older than 72 hours without the `events:import` capability (400 days with it).","example":"2026-10-03T14:05:10.020Z","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.5.occurredAt","typeLabel":"string\u003cdate-time>"},"searchId":{"type":"string","minLength":1,"maxLength":128,"description":"The `searchId` of the search response whose results were drawn.","example":"srch_01k7q3x9h4e8rb2d6m0z5a7c1n","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.5.searchId","typeLabel":"string"},"surface":{"type":"string","enum":["home","results","listing","site_search","profile","widget","assistant","other"],"description":"Where on the site the list was drawn.","example":"results","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.5.surface","typeLabel":"enum\u003cstring>"},"suppliers":{"type":"array","items":{"type":"object","properties":{"supplierId":{"type":"string","minLength":1,"maxLength":128,"description":"The MarketBox supplier id. Must belong to this project, or the event is rejected.","example":"sup_01kv60qh3m7wznp8s0d2rk9abc","isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.5.suppliers.items.[INDEX].supplierId","typeLabel":"string"},"position":{"type":"integer","minimum":0,"description":"0-based rank in the list as drawn (the same number a search response returns).","example":0,"isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.5.suppliers.items.[INDEX].position","typeLabel":"integer"}},"required":["supplierId","position"],"additionalProperties":false,"uniqueKey":"events.items.[INDEX].oneOf.5.suppliers.items.[INDEX]","typeLabel":"object"},"maxItems":100,"description":"The suppliers actually put on the page, in the order drawn, at most 100. Every id must belong to this project, or the whole event is rejected.","example":[{"supplierId":"sup_01kv60qh3m7wznp8s0d2rk9abc","position":0},{"supplierId":"sup_01kv60qh3m7wznp8s0d2rk9def","position":1}],"isRequired":true,"uniqueKey":"events.items.[INDEX].oneOf.5.suppliers","typeLabel":"object[]"},"sessionKey":{"type":"string","minLength":1,"maxLength":64,"description":"An opaque per-session key you hash yourself, at most 64 characters. Never an email, IP or user id. Alternatively the `X-MB-Session-Key` header.","example":"sess-example-01","uniqueKey":"events.items.[INDEX].oneOf.5.sessionKey","typeLabel":"string"},"path":{"type":"string","maxLength":300,"description":"The page path, at most 300 characters. The query string is stripped on receipt.","example":"/en-ca/book/results","uniqueKey":"events.items.[INDEX].oneOf.5.path","typeLabel":"string"},"serviceId":{"type":"string","minLength":1,"maxLength":128,"description":"The service the list or search was for, when there was one.","example":"srv_01kv60qg12e82acr78edfnjhvv","uniqueKey":"events.items.[INDEX].oneOf.5.serviceId","typeLabel":"string"},"locale":{"type":"string","minLength":2,"maxLength":16,"description":"The page locale, as a BCP 47 tag.","example":"en-CA","uniqueKey":"events.items.[INDEX].oneOf.5.locale","typeLabel":"string"},"h3":{"type":"string","pattern":"^88[0-9a-f]{13}$","description":"The place in the event as a resolution-8 H3 cell. Send this or `lat`/`lng`, not both.","example":"882b8e4a0dfffff","uniqueKey":"events.items.[INDEX].oneOf.5.h3","typeLabel":"string"},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.","example":43.6532,"uniqueKey":"events.items.[INDEX].oneOf.5.lat","typeLabel":"number"},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.","example":-79.3832,"uniqueKey":"events.items.[INDEX].oneOf.5.lng","typeLabel":"number"}},"additionalProperties":false,"uniqueKey":"events.items.[INDEX].oneOf.5","typeLabel":"object"}],"uniqueKey":"events.items.[INDEX]","typeLabel":"object"},"minItems":1,"maxItems":500,"example":[{"eventId":"lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b","type":"search.rendered","occurredAt":"2026-10-03T14:05:10.020Z","sessionKey":"sess-example-01","searchId":"srch_01k7q3x9h4e8rb2d6m0z5a7c1n","surface":"results","path":"/en-ca/book/results","suppliers":[{"supplierId":"sup_01kv60qh3m7wznp8s0d2rk9abc","position":0},{"supplierId":"sup_01kv60qh3m7wznp8s0d2rk9def","position":1}]},{"eventId":"imp_2b7e1d5c-9f4a-4b8e-a3c6-7d0e2f1a9b4c","type":"impression","occurredAt":"2026-10-03T14:05:11.900Z","sessionKey":"sess-example-01","listId":"lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b","supplierId":"sup_01kv60qh3m7wznp8s0d2rk9def","position":1},{"eventId":"clk_9d7e1f0a-2b4c-4d8e-9f3a-6b5c4d3e2f1a","type":"click","occurredAt":"2026-10-03T14:05:20.004Z","sessionKey":"sess-example-01","impressionId":"imp_2b7e1d5c-9f4a-4b8e-a3c6-7d0e2f1a9b4c","supplierId":"sup_01kv60qh3m7wznp8s0d2rk9def"}],"description":"The events, at most 500 per request (and 256 KB in all). Each is validated on its own.","isRequired":true,"uniqueKey":"events","typeLabel":"object[]"}},"required":["events"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"events":[{"eventId":"lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b","type":"search.rendered","occurredAt":"2026-10-03T14:05:10.020Z","sessionKey":"sess-example-01","searchId":"srch_01k7q3x9h4e8rb2d6m0z5a7c1n","surface":"results","path":"/en-ca/book/results","suppliers":[{"supplierId":"sup_01kv60qh3m7wznp8s0d2rk9abc","position":0},{"supplierId":"sup_01kv60qh3m7wznp8s0d2rk9def","position":1}]},{"eventId":"imp_2b7e1d5c-9f4a-4b8e-a3c6-7d0e2f1a9b4c","type":"impression","occurredAt":"2026-10-03T14:05:11.900Z","sessionKey":"sess-example-01","listId":"lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b","supplierId":"sup_01kv60qh3m7wznp8s0d2rk9def","position":1},{"eventId":"clk_9d7e1f0a-2b4c-4d8e-9f3a-6b5c4d3e2f1a","type":"click","occurredAt":"2026-10-03T14:05:20.004Z","sessionKey":"sess-example-01","impressionId":"imp_2b7e1d5c-9f4a-4b8e-a3c6-7d0e2f1a9b4c","supplierId":"sup_01kv60qh3m7wznp8s0d2rk9def"}]}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"aceb59cd-173e-4768-a7b8-ac8576b11b4e":{"description":"The batch was read: what was accepted and what was not","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"integer","description":"Events accepted and recorded. `accepted + rejected.length` is the number sent. When nothing could be recorded the answer is 503, not 202, so retry on it.","example":41,"isRequired":true,"uniqueKey":"accepted","typeLabel":"integer"},"duplicates":{"type":"integer","description":"Always 0 for now. A repeated `eventId` is accepted and counted once by the rollup, so a retry never double-counts; this field will report what the rollup collapsed.","example":0,"isRequired":true,"uniqueKey":"duplicates","typeLabel":"integer"},"rejected":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"The position of the rejected element in `events`, 0-based.","example":3,"isRequired":true,"uniqueKey":"rejected.items.[INDEX].index","typeLabel":"integer"},"eventId":{"oneOf":[{"type":"string","description":"Its `eventId`, or null when the element had none.","example":"clk_9d7e1f0a-2b4c-4d8e-9f3a-6b5c4d3e2f1a","isRequired":true,"uniqueKey":"rejected.items.[INDEX].eventId.oneOf.0","typeLabel":"string"},{"type":"null","description":"Its `eventId`, or null when the element had none.","example":"clk_9d7e1f0a-2b4c-4d8e-9f3a-6b5c4d3e2f1a","isRequired":true,"uniqueKey":"rejected.items.[INDEX].eventId.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"rejected.items.[INDEX].eventId","typeLabel":"string | null"},"code":{"type":"string","enum":["INVALID_EVENT","UNKNOWN_SUPPLIER","OCCURRED_AT_TOO_OLD","OCCURRED_AT_IN_FUTURE"],"description":"`INVALID_EVENT`: the element does not match its type's shape (`message` says where). `UNKNOWN_SUPPLIER`: a `supplierId` is not in this project. `OCCURRED_AT_TOO_OLD`: older than 72 hours (400 days with `events:import`). `OCCURRED_AT_IN_FUTURE`: more than 24 hours ahead.","example":"UNKNOWN_SUPPLIER","isRequired":true,"uniqueKey":"rejected.items.[INDEX].code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"What was wrong, for a person.","example":"supplier sup_01kv60qh3m7wznp8s0d2rk9abc is not in this project","isRequired":true,"uniqueKey":"rejected.items.[INDEX].message","typeLabel":"string"}},"required":["index","eventId","code","message"],"uniqueKey":"rejected.items.[INDEX]","typeLabel":"object"},"description":"The events not accepted, in batch order. Fix and resend only these.","isRequired":true,"uniqueKey":"rejected","typeLabel":"object[]"}},"required":["accepted","duplicates","rejected"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"accepted":41,"duplicates":0,"rejected":[{"index":3,"eventId":"clk_9d7e1f0a-2b4c-4d8e-9f3a-6b5c4d3e2f1a","code":"UNKNOWN_SUPPLIER","message":"supplier sup_01kv60qh3m7wznp8s0d2rk9abc is not in this project"}]}}},"exampleType":"generated"}},"exampleType":"generated"},"25e62a27-d2a6-4640-92f8-31e33a2f57ee":{"description":"Not a batch: no `events` array, or more than 500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code, e.g. NOT_FOUND.","isRequired":true,"uniqueKey":"code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable description of what went wrong.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"statusCode":{"type":"integer","description":"The HTTP status code of this response.","isRequired":true,"uniqueKey":"statusCode","typeLabel":"integer"},"requestId":{"type":"string","description":"The id of this request, also returned as the X-Request-Id header. Quote it in a support ticket.","isRequired":true,"uniqueKey":"requestId","typeLabel":"string"}},"required":["code","message","statusCode","requestId"],"example":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"}}},"exampleType":"generated"}},"exampleType":"generated"},"435338be-0909-42fb-b233-87604dc3a7be":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code, e.g. NOT_FOUND.","isRequired":true,"uniqueKey":"code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable description of what went wrong.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"statusCode":{"type":"integer","description":"The HTTP status code of this response.","isRequired":true,"uniqueKey":"statusCode","typeLabel":"integer"},"requestId":{"type":"string","description":"The id of this request, also returned as the X-Request-Id header. Quote it in a support ticket.","isRequired":true,"uniqueKey":"requestId","typeLabel":"string"}},"required":["code","message","statusCode","requestId"],"example":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"}}},"exampleType":"generated"}},"exampleType":"generated"},"f9c531d6-99ef-4fdc-bd68-504bda71aeaa":{"description":"API key lacks `events:write` or cannot access this project","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code, e.g. NOT_FOUND.","isRequired":true,"uniqueKey":"code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable description of what went wrong.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"statusCode":{"type":"integer","description":"The HTTP status code of this response.","isRequired":true,"uniqueKey":"statusCode","typeLabel":"integer"},"requestId":{"type":"string","description":"The id of this request, also returned as the X-Request-Id header. Quote it in a support ticket.","isRequired":true,"uniqueKey":"requestId","typeLabel":"string"}},"required":["code","message","statusCode","requestId"],"example":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"}}},"exampleType":"generated"}},"exampleType":"generated"},"11cfe359-af53-4e8b-a260-7344311065e4":{"description":"The body is over 256 KB; nothing was read","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code, e.g. NOT_FOUND.","isRequired":true,"uniqueKey":"code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable description of what went wrong.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"statusCode":{"type":"integer","description":"The HTTP status code of this response.","isRequired":true,"uniqueKey":"statusCode","typeLabel":"integer"},"requestId":{"type":"string","description":"The id of this request, also returned as the X-Request-Id header. Quote it in a support ticket.","isRequired":true,"uniqueKey":"requestId","typeLabel":"string"}},"required":["code","message","statusCode","requestId"],"example":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"}}},"exampleType":"generated"}},"exampleType":"generated"},"5f5640ec-b2f1-4b31-ab4e-d209e1ff5729":{"description":"Too many requests from this key; retry after a second","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code, e.g. NOT_FOUND.","isRequired":true,"uniqueKey":"code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable description of what went wrong.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"statusCode":{"type":"integer","description":"The HTTP status code of this response.","isRequired":true,"uniqueKey":"statusCode","typeLabel":"integer"},"requestId":{"type":"string","description":"The id of this request, also returned as the X-Request-Id header. Quote it in a support ticket.","isRequired":true,"uniqueKey":"requestId","typeLabel":"string"}},"required":["code","message","statusCode","requestId"],"example":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"}}},"exampleType":"generated"}},"exampleType":"generated"},"31984ec8-f038-4d09-a2f2-3e67a41d0200":{"description":"MarketBox could not check or record the batch (a dependency was down); nothing was recorded. Retry the same batch after `Retry-After` seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code, e.g. NOT_FOUND.","isRequired":true,"uniqueKey":"code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable description of what went wrong.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"statusCode":{"type":"integer","description":"The HTTP status code of this response.","isRequired":true,"uniqueKey":"statusCode","typeLabel":"integer"},"requestId":{"type":"string","description":"The id of this request, also returned as the X-Request-Id header. Quote it in a support ticket.","isRequired":true,"uniqueKey":"requestId","typeLabel":"string"}},"required":["code","message","statusCode","requestId"],"example":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"code":"NOT_FOUND","message":"Booking not found","statusCode":404,"requestId":"a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"db6d1cf6-4a08-4a4c-92da-023445e576e6":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"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`.","scopes":[],"schemeName":"ApiKeyAuth"}}},"servers":{"7f0c0cfd-7cba-4616-861f-ca7611ae4010":{"url":"https://apiv2.gomarketbox.com","description":"MarketBox Open API"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"apiKey","in":"header","name":"x-api-key","description":"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`.","scopes":[],"schemeName":"ApiKeyAuth"},"schema":{"title":"x-api-key","type":"string","description":"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`.","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"ApiKeyAuth","name":"x-api-key"}],"title":"ApiKeyAuth"}]},"originalFileLocation":"api-reference/openapi.json"},"subdomain":"marketboxinc","siteName":"MarketBox API","title":"Report what your site showed: rendered searches, lists, impressions, clicks, profile views - MarketBox API","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-19T15:10:28.616Z","originalFileLocation":"api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" 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, so it reports them here and each supplier sees them in their Search insights. Send from your server, batched: every 10 seconds or at 500 events, whichever comes first. The API key needs the events:write capability, granted by name on the application in the dashboard (a key without it — including a legacy key or a * key — gets 403). Event types. search.rendered: the results of a MarketBox search were drawn (carry its searchId and the supplier ids drawn, in order, with their 0-based position). This is what makes a search count: a search with no render counts for nothing, not as Shown, not as Seen, not on the demand map. opportunity: any list that includes suppliers was drawn (home page, a city page, a widget), one per list render; an opportunity carrying a searchId counts as the render too. impression: a supplier\u0026#x27;s card was at least 50 % in the viewport for the first time in that list (IntersectionObserver, threshold 0.5); carries the opportunity\u0026#x27;s eventId as listId. click: the client opened a profile or card from a list; carries impressionId (or listId + supplierId when you do not track impressions). profile_view: a profile page loaded, from anywhere. coverage_miss: a client entered an address and your site found nobody without calling a MarketBox search. Each event is validated on its own. The response is always 202 with accepted and the rejected ones by index and code; a rejected event never fails the batch. The whole request fails only on auth (401/403), size (413: over 256 KB) or shape (400: no events, or over 500). eventId is your idempotency key: on a 429 or 5xx retry the same batch with the same ids and nothing is counted twice. occurredAt must be within 24 hours ahead and 72 hours back of receipt; a key holding events:import may send up to 400 days back (a back-fill), and those events are stored as imported. Give up on an event after 72 hours. Privacy. sessionKey is opaque and hashed by you — never an email, IP or user id. A place is sent as a resolution-8 H3 cell or as lat/lng; coordinates are reduced to the cell on receipt and never stored. path loses its query string. Supplier ids must belong to this project; searchId, listId and impressionId are stored as you sent them. About 50 requests a second per key are allowed, with bursts of 100; past that a 429 with Retry-After.\">\u003cmeta data-mint-head name=\"application-name\" content=\"MarketBox API\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Report what your site showed: rendered searches, lists, impressions, clicks, profile views - MarketBox API\">\u003cmeta data-mint-head property=\"og:description\" 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, so it reports them here and each supplier sees them in their Search insights. Send from your server, batched: every 10 seconds or at 500 events, whichever comes first. The API key needs the events:write capability, granted by name on the application in the dashboard (a key without it — including a legacy key or a * key — gets 403). Event types. search.rendered: the results of a MarketBox search were drawn (carry its searchId and the supplier ids drawn, in order, with their 0-based position). This is what makes a search count: a search with no render counts for nothing, not as Shown, not as Seen, not on the demand map. opportunity: any list that includes suppliers was drawn (home page, a city page, a widget), one per list render; an opportunity carrying a searchId counts as the render too. impression: a supplier\u0026#x27;s card was at least 50 % in the viewport for the first time in that list (IntersectionObserver, threshold 0.5); carries the opportunity\u0026#x27;s eventId as listId. click: the client opened a profile or card from a list; carries impressionId (or listId + supplierId when you do not track impressions). profile_view: a profile page loaded, from anywhere. coverage_miss: a client entered an address and your site found nobody without calling a MarketBox search. Each event is validated on its own. The response is always 202 with accepted and the rejected ones by index and code; a rejected event never fails the batch. The whole request fails only on auth (401/403), size (413: over 256 KB) or shape (400: no events, or over 500). eventId is your idempotency key: on a 429 or 5xx retry the same batch with the same ids and nothing is counted twice. occurredAt must be within 24 hours ahead and 72 hours back of receipt; a key holding events:import may send up to 400 days back (a back-fill), and those events are stored as imported. Give up on an event after 72 hours. Privacy. sessionKey is opaque and hashed by you — never an email, IP or user id. A place is sent as a resolution-8 H3 cell or as lat/lng; coordinates are reduced to the cell on receipt and never stored. path loses its query string. Supplier ids must belong to this project; searchId, listId and impressionId are stored as you sent them. About 50 requests a second per key are allowed, with bursts of 100; past that a 429 with Retry-After.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"MarketBox API\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.gomarketbox.com/api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://marketboxinc.mintlify.site/_mintlify/api/og/v2?division=Events\u0026amp;title=Report+what+your+site+showed%3A+rendered+searches%2C+lists%2C+impressions%2C+clicks%2C+profile+views\u0026amp;description=MarketBox+runs+the+search%3B+your+site+draws+the+results.+Only+your+site+knows+which+suppliers+it+actually+put+on+the+page%2C+which+cards+reached+the+screen+and+whi\u0026amp;theme=3a79fb7765978cda15c7035f\u0026amp;signature=ef159dbd9254298c9f3c27362fbeda474b87041ed73d93c9853fc3fc214c44cc\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Report what your site showed: rendered searches, lists, impressions, clicks, profile views - MarketBox API\">\u003cmeta data-mint-head name=\"twitter:description\" 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, so it reports them here and each supplier sees them in their Search insights. Send from your server, batched: every 10 seconds or at 500 events, whichever comes first. The API key needs the events:write capability, granted by name on the application in the dashboard (a key without it — including a legacy key or a * key — gets 403). Event types. search.rendered: the results of a MarketBox search were drawn (carry its searchId and the supplier ids drawn, in order, with their 0-based position). This is what makes a search count: a search with no render counts for nothing, not as Shown, not as Seen, not on the demand map. opportunity: any list that includes suppliers was drawn (home page, a city page, a widget), one per list render; an opportunity carrying a searchId counts as the render too. impression: a supplier\u0026#x27;s card was at least 50 % in the viewport for the first time in that list (IntersectionObserver, threshold 0.5); carries the opportunity\u0026#x27;s eventId as listId. click: the client opened a profile or card from a list; carries impressionId (or listId + supplierId when you do not track impressions). profile_view: a profile page loaded, from anywhere. coverage_miss: a client entered an address and your site found nobody without calling a MarketBox search. Each event is validated on its own. The response is always 202 with accepted and the rejected ones by index and code; a rejected event never fails the batch. The whole request fails only on auth (401/403), size (413: over 256 KB) or shape (400: no events, or over 500). eventId is your idempotency key: on a 429 or 5xx retry the same batch with the same ids and nothing is counted twice. occurredAt must be within 24 hours ahead and 72 hours back of receipt; a key holding events:import may send up to 400 days back (a back-fill), and those events are stored as imported. Give up on an event after 72 hours. Privacy. sessionKey is opaque and hashed by you — never an email, IP or user id. A place is sent as a resolution-8 H3 cell or as lat/lng; coordinates are reduced to the cell on receipt and never stored. path loses its query string. Supplier ids must belong to this project; searchId, listId and impressionId are stored as you sent them. About 50 requests a second per key are allowed, with bursts of 100; past that a 429 with Retry-After.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://marketboxinc.mintlify.site/_mintlify/api/og/v2?division=Events\u0026amp;title=Report+what+your+site+showed%3A+rendered+searches%2C+lists%2C+impressions%2C+clicks%2C+profile+views\u0026amp;description=MarketBox+runs+the+search%3B+your+site+draws+the+results.+Only+your+site+knows+which+suppliers+it+actually+put+on+the+page%2C+which+cards+reached+the+screen+and+whi\u0026amp;theme=3a79fb7765978cda15c7035f\u0026amp;signature=ef159dbd9254298c9f3c27362fbeda474b87041ed73d93c9853fc3fc214c44cc\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/marketboxinc/etccUjaGielLGJIh/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"MarketBox API\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#0087EE\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.gomarketbox.com/api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/events/report-what-your-site-showed%3A-rendered-searches-lists-impressions-clicks-profile-views.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.gomarketbox.com/#organization\",\"name\":\"MarketBox API\",\"url\":\"https://docs.gomarketbox.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/marketboxinc/ajdEqdrEaJkvfx4T/logo/light.svg?fit=max\u0026auto=format\u0026n=ajdEqdrEaJkvfx4T\u0026q=85\u0026s=655948ee6454a1e06bfe0dffda47c7cc\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.gomarketbox.com#website\",\"name\":\"MarketBox API\",\"url\":\"https://docs.gomarketbox.com\",\"publisher\":{\"@id\":\"https://docs.gomarketbox.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.gomarketbox.com/api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views#webpage\",\"url\":\"https://docs.gomarketbox.com/api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views\",\"name\":\"Report what your site showed: rendered searches, lists, impressions, clicks, profile views\",\"description\":\"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, so it reports them here and each supplier sees them in their Search insights. Send from your server, batched: every 10 seconds or at 500 events, whichever comes first. The API key needs the events:write capability, granted by name on the application in the dashboard (a key without it — including a legacy key or a * key — gets 403). Event types. search.rendered: the results of a MarketBox search were drawn (carry its searchId and the supplier ids drawn, in order, with their 0-based position). This is what makes a search count: a search with no render counts for nothing, not as Shown, not as Seen, not on the demand map. opportunity: any list that includes suppliers was drawn (home page, a city page, a widget), one per list render; an opportunity carrying a searchId counts as the render too. impression: a supplier's card was at least 50 % in the viewport for the first time in that list (IntersectionObserver, threshold 0.5); carries the opportunity's eventId as listId. click: the client opened a profile or card from a list; carries impressionId (or listId + supplierId when you do not track impressions). profile_view: a profile page loaded, from anywhere. coverage_miss: a client entered an address and your site found nobody without calling a MarketBox search. Each event is validated on its own. The response is always 202 with accepted and the rejected ones by index and code; a rejected event never fails the batch. The whole request fails only on auth (401/403), size (413: over 256 KB) or shape (400: no events, or over 500). eventId is your idempotency key: on a 429 or 5xx retry the same batch with the same ids and nothing is counted twice. occurredAt must be within 24 hours ahead and 72 hours back of receipt; a key holding events:import may send up to 400 days back (a back-fill), and those events are stored as imported. Give up on an event after 72 hours. Privacy. sessionKey is opaque and hashed by you — never an email, IP or user id. A place is sent as a resolution-8 H3 cell or as lat/lng; coordinates are reduced to the cell on receipt and never stored. path loses its query string. Supplier ids must belong to this project; searchId, listId and impressionId are stored as you sent them. About 50 requests a second per key are allowed, with bursts of 100; past that a 429 with Retry-After.\",\"dateModified\":\"2026-11-19T15:10:28.616Z\",\"isPartOf\":{\"@id\":\"https://docs.gomarketbox.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.gomarketbox.com/api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.gomarketbox.com/api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Endpoints\",\"item\":\"https://docs.gomarketbox.com/api-reference/events/report-site-events-straight-from-the-browser-publishable-key-no-response-body\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Events\",\"item\":\"https://docs.gomarketbox.com/api-reference/events/report-site-events-straight-from-the-browser-publishable-key-no-response-body\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Report what your site showed: rendered searches, lists, impressions, clicks, profile views\",\"item\":\"https://docs.gomarketbox.com/api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.gomarketbox.com/api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views#apireference\",\"headline\":\"Report what your site showed: rendered searches, lists, impressions, clicks, profile views\",\"name\":\"Report what your site showed: rendered searches, lists, impressions, clicks, profile views\",\"description\":\"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, so it reports them here and each supplier sees them in their Search insights. Send from your server, batched: every 10 seconds or at 500 events, whichever comes first. The API key needs the events:write capability, granted by name on the application in the dashboard (a key without it — including a legacy key or a * key — gets 403). Event types. search.rendered: the results of a MarketBox search were drawn (carry its searchId and the supplier ids drawn, in order, with their 0-based position). This is what makes a search count: a search with no render counts for nothing, not as Shown, not as Seen, not on the demand map. opportunity: any list that includes suppliers was drawn (home page, a city page, a widget), one per list render; an opportunity carrying a searchId counts as the render too. impression: a supplier's card was at least 50 % in the viewport for the first time in that list (IntersectionObserver, threshold 0.5); carries the opportunity's eventId as listId. click: the client opened a profile or card from a list; carries impressionId (or listId + supplierId when you do not track impressions). profile_view: a profile page loaded, from anywhere. coverage_miss: a client entered an address and your site found nobody without calling a MarketBox search. Each event is validated on its own. The response is always 202 with accepted and the rejected ones by index and code; a rejected event never fails the batch. The whole request fails only on auth (401/403), size (413: over 256 KB) or shape (400: no events, or over 500). eventId is your idempotency key: on a 429 or 5xx retry the same batch with the same ids and nothing is counted twice. occurredAt must be within 24 hours ahead and 72 hours back of receipt; a key holding events:import may send up to 400 days back (a back-fill), and those events are stored as imported. Give up on an event after 72 hours. Privacy. sessionKey is opaque and hashed by you — never an email, IP or user id. A place is sent as a resolution-8 H3 cell or as lat/lng; coordinates are reduced to the cell on receipt and never stored. path loses its query string. Supplier ids must belong to this project; searchId, listId and impressionId are stored as you sent them. About 50 requests a second per key are allowed, with bursts of 100; past that a 429 with Retry-After.\",\"url\":\"https://docs.gomarketbox.com/api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views\",\"mainEntityOfPage\":{\"@id\":\"https://docs.gomarketbox.com/api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views#webpage\"},\"dateModified\":\"2026-11-19T15:10:28.616Z\",\"publisher\":{\"@id\":\"https://docs.gomarketbox.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.gomarketbox.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"MarketBox API\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"MarketBox API\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/events/report-what-your-site-showed%3A-rendered-searches-lists-impressions-clicks-profile-views.md","siteName":"MarketBox API","nav":{"global":null,"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":""}]},{"tab":"API reference","groups":[{"group":"Overview","pages":[{"title":"API reference","href":"/api-reference/introduction"}]},{"group":"Endpoints","pages":[{"group":"Events","pages":[{"title":"Report site events straight from the browser (publishable key, no response body)","description":"The browser path for the same events as `POST /events`, for sites without a server of their own and for MarketBox’s own widget. Built for `navigator.sendBeacon` and `fetch(…, { keepalive: true })` on a page that may be closing, so nothing about it needs a header: the credential is the publishable key in `?key=pk_…`, the body may be `text/plain` as well as `application/json` (no CORS preflight), and the answer is 204 with no body. `@mb-core/insights-beacon` does all of this for you.\n\n**The publishable key** is minted with the application and shown on the API Access screen beside the API key. It is public by design — it ships in your page — and can only do this: send events, from the exact origins listed on the application (`https://book.acme.com`, never `*`). The browser’s `Origin` header must be one of them; a missing or other origin is refused (403). Keep the API key on your server; it is never accepted here (401).\n\n**Limits.** At most 50 events and 64 KB per beacon (413 past either, nothing read). About 50 beacons a second per key, with bursts of 100 (429 past that). Each event is validated on its own exactly as on `POST /events`, with the same rules: `occurredAt` within 24 hours ahead and 72 hours back, supplier ids of this project, a place as an H3 cell or `lat`/`lng` reduced on receipt. A rejected event is dropped silently (the 204 says nothing); send from your server with `POST /events` when you want the rejections back. Events are stored with `channel: \"browser\"`; a `searchId` is kept as sent.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/events/beacon","href":"/api-reference/events/report-site-events-straight-from-the-browser-publishable-key-no-response-body"},{"title":"Report what your site showed: rendered searches, lists, impressions, clicks, profile views","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/events","href":"/api-reference/events/report-what-your-site-showed:-rendered-searches-lists-impressions-clicks-profile-views"}]},{"group":"Supplier plane","pages":[{"title":"Whether the signed-in person may use the supplier plane, and why not","description":"Answers 200 for every signed-in person, with `allowed` and a `reasonCode`; it never answers 4xx for a person-level outcome. Call it on sign-in, and use the plane with the returned `supplierId` only when `allowed` is true; otherwise show `message`. `reasonCode` is one of: `SUPPLIER_ACTIVE` (allowed), `SUPPLIER_RECORD_INACTIVE`, `NO_ACCOUNT`, `NOT_A_MEMBER`, `MEMBERSHIP_INACTIVE`, `NO_SUPPLIER_ROLE` and `SUPPLIER_NOT_LINKED`. The other `/suppliers/me` routes refuse with the same codes and messages. It describes the person: `X-MB-Acting-Role` is ignored, and `roles` lists every role they hold here. Only the app’s credentials still fail: a missing or invalid user token (401), a key without standard access (403 `CAPABILITY_NOT_GRANTED`), or a project outside the key’s scope (403). Requires the API key and the person’s user token.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/access","href":"/api-reference/supplier-plane/whether-the-signed-in-person-may-use-the-supplier-plane-and-why-not"},{"title":"List the signed-in supplier’s bookings","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/bookings","href":"/api-reference/supplier-plane/list-the-signed-in-supplier’s-bookings"},{"title":"One of the signed-in supplier’s bookings, with services and participants","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/bookings/{bookingId}","href":"/api-reference/supplier-plane/one-of-the-signed-in-supplier’s-bookings-with-services-and-participants"},{"title":"Move one of the signed-in supplier’s bookings to another time","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/suppliers/me/bookings/{bookingId}","href":"/api-reference/supplier-plane/move-one-of-the-signed-in-supplier’s-bookings-to-another-time"},{"title":"The signed-in supplier’s own attendance report on one of their bookings","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/bookings/{bookingId}/reports","href":"/api-reference/supplier-plane/the-signed-in-supplier’s-own-attendance-report-on-one-of-their-bookings"},{"title":"File the signed-in supplier’s attendance report on one of their bookings","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/bookings/{bookingId}/reports","href":"/api-reference/supplier-plane/file-the-signed-in-supplier’s-attendance-report-on-one-of-their-bookings"},{"title":"Cancel one of the signed-in supplier’s bookings","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/bookings/{bookingId}/cancel","href":"/api-reference/supplier-plane/cancel-one-of-the-signed-in-supplier’s-bookings"},{"title":"List the signed-in supplier’s schedules","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/schedules","href":"/api-reference/supplier-plane/list-the-signed-in-supplier’s-schedules"},{"title":"Create a schedule for the signed-in supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/schedules","href":"/api-reference/supplier-plane/create-a-schedule-for-the-signed-in-supplier"},{"title":"Get one of the signed-in supplier’s schedules","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/schedules/{scheduleId}","href":"/api-reference/supplier-plane/get-one-of-the-signed-in-supplier’s-schedules"},{"title":"Delete one of the signed-in supplier’s schedules","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/me/schedules/{scheduleId}","href":"/api-reference/supplier-plane/delete-one-of-the-signed-in-supplier’s-schedules"},{"title":"Update one of the signed-in supplier’s schedules","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/suppliers/me/schedules/{scheduleId}","href":"/api-reference/supplier-plane/update-one-of-the-signed-in-supplier’s-schedules"},{"title":"Clone one of the signed-in supplier’s schedules","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/schedules/{scheduleId}/clone","href":"/api-reference/supplier-plane/clone-one-of-the-signed-in-supplier’s-schedules"},{"title":"Move the signed-in supplier’s schedules and blocked times to their profile zone","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/availability-timezone/apply-profile","href":"/api-reference/supplier-plane/move-the-signed-in-supplier’s-schedules-and-blocked-times-to-their-profile-zone"},{"title":"List the signed-in supplier’s blocked times","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/blocked-times","href":"/api-reference/supplier-plane/list-the-signed-in-supplier’s-blocked-times"},{"title":"Create a blocked time for the signed-in supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/blocked-times","href":"/api-reference/supplier-plane/create-a-blocked-time-for-the-signed-in-supplier"},{"title":"Get one of the signed-in supplier’s blocked times","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/blocked-times/{blockedTimeId}","href":"/api-reference/supplier-plane/get-one-of-the-signed-in-supplier’s-blocked-times"},{"title":"Delete one of the signed-in supplier’s blocked times","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/me/blocked-times/{blockedTimeId}","href":"/api-reference/supplier-plane/delete-one-of-the-signed-in-supplier’s-blocked-times"},{"title":"Update one of the signed-in supplier’s blocked times","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/suppliers/me/blocked-times/{blockedTimeId}","href":"/api-reference/supplier-plane/update-one-of-the-signed-in-supplier’s-blocked-times"},{"title":"The signed-in supplier’s Week \u0026 demand view","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/demand","href":"/api-reference/supplier-plane/the-signed-in-supplier’s-week-\u0026-demand-view"},{"title":"Dismiss one of the signed-in supplier’s demand suggestions for 90 days","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/demand/suggestions/{key}/dismiss","href":"/api-reference/supplier-plane/dismiss-one-of-the-signed-in-supplier’s-demand-suggestions-for-90-days"},{"title":"Undo a dismissal: the suggestion shows again when the data still supports it","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/me/demand/suggestions/{key}/dismiss","href":"/api-reference/supplier-plane/undo-a-dismissal:-the-suggestion-shows-again-when-the-data-still-supports-it"},{"title":"The signed-in supplier’s Search insights","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/search-insights","href":"/api-reference/supplier-plane/the-signed-in-supplier’s-search-insights"},{"title":"The signed-in supplier’s own profile","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me","href":"/api-reference/supplier-plane/the-signed-in-supplier’s-own-profile"},{"title":"Update the signed-in supplier’s own profile","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/suppliers/me","href":"/api-reference/supplier-plane/update-the-signed-in-supplier’s-own-profile"},{"title":"Get a presigned URL to upload the signed-in supplier’s photo","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/avatar/upload-url","href":"/api-reference/supplier-plane/get-a-presigned-url-to-upload-the-signed-in-supplier’s-photo"},{"title":"Attach the uploaded photo to the signed-in supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/projects/{projectId}/suppliers/me/avatar","href":"/api-reference/supplier-plane/attach-the-uploaded-photo-to-the-signed-in-supplier"},{"title":"Remove the signed-in supplier’s photo","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/me/avatar","href":"/api-reference/supplier-plane/remove-the-signed-in-supplier’s-photo"},{"title":"List the signed-in supplier’s travel zones","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/travel-zones","href":"/api-reference/supplier-plane/list-the-signed-in-supplier’s-travel-zones"},{"title":"Create a travel zone for the signed-in supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/travel-zones","href":"/api-reference/supplier-plane/create-a-travel-zone-for-the-signed-in-supplier"},{"title":"Get one of the signed-in supplier’s travel zones","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/travel-zones/{travelZoneId}","href":"/api-reference/supplier-plane/get-one-of-the-signed-in-supplier’s-travel-zones"},{"title":"Delete one of the signed-in supplier’s travel zones","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/me/travel-zones/{travelZoneId}","href":"/api-reference/supplier-plane/delete-one-of-the-signed-in-supplier’s-travel-zones"},{"title":"Update one of the signed-in supplier’s travel zones","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/suppliers/me/travel-zones/{travelZoneId}","href":"/api-reference/supplier-plane/update-one-of-the-signed-in-supplier’s-travel-zones"},{"title":"List the venues the signed-in supplier may be scheduled at","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/locations","href":"/api-reference/supplier-plane/list-the-venues-the-signed-in-supplier-may-be-scheduled-at"},{"title":"List the signed-in supplier’s alerts","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/alerts","href":"/api-reference/supplier-plane/list-the-signed-in-supplier’s-alerts"},{"title":"The signed-in supplier’s unread count and open conditions","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/alerts/summary","href":"/api-reference/supplier-plane/the-signed-in-supplier’s-unread-count-and-open-conditions"},{"title":"Mark all of the signed-in supplier’s alerts read","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/alerts/read-all","href":"/api-reference/supplier-plane/mark-all-of-the-signed-in-supplier’s-alerts-read"},{"title":"Mark one of the signed-in supplier’s alerts read","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/me/alerts/{alertId}/read","href":"/api-reference/supplier-plane/mark-one-of-the-signed-in-supplier’s-alerts-read"}]},{"group":"Bookings","pages":[{"title":"List bookings for a project","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/bookings","href":"/api-reference/bookings/list-bookings-for-a-project"},{"title":"Create a new booking","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/bookings","href":"/api-reference/bookings/create-a-new-booking"},{"title":"Get a booking by ID","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/bookings/{bookingId}","href":"/api-reference/bookings/get-a-booking-by-id"},{"title":"Soft-delete a booking","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/bookings/{bookingId}","href":"/api-reference/bookings/soft-delete-a-booking"},{"title":"Reschedule or update a booking","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/bookings/{bookingId}","href":"/api-reference/bookings/reschedule-or-update-a-booking"},{"title":"Get a booking with its services, participants, notes, reports and party names","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/bookings/{bookingId}/aggregate","href":"/api-reference/bookings/get-a-booking-with-its-services-participants-notes-reports-and-party-names"},{"title":"Change a booking status","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/bookings/{bookingId}/status","href":"/api-reference/bookings/change-a-booking-status"},{"title":"List bookings for a supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/{supplierId}/bookings","href":"/api-reference/bookings/list-bookings-for-a-supplier"},{"title":"List bookings for a client","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/clients/{clientId}/bookings","href":"/api-reference/bookings/list-bookings-for-a-client"},{"title":"List participants on a booking","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/bookings/{bookingId}/participants","href":"/api-reference/bookings/list-participants-on-a-booking"},{"title":"Register a participant on a booking","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/bookings/{bookingId}/participants","href":"/api-reference/bookings/register-a-participant-on-a-booking"},{"title":"Get a single booking participant","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/bookings/{bookingId}/participants/{clientId}","href":"/api-reference/bookings/get-a-single-booking-participant"},{"title":"Cancel a booking participant","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/bookings/{bookingId}/participants/{clientId}","href":"/api-reference/bookings/cancel-a-booking-participant"},{"title":"Check in a participant","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/bookings/{bookingId}/participants/{clientId}/check-in","href":"/api-reference/bookings/check-in-a-participant"},{"title":"List booking notes","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/bookings/{bookingId}/notes","href":"/api-reference/bookings/list-booking-notes"},{"title":"Create a booking note","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/bookings/{bookingId}/notes","href":"/api-reference/bookings/create-a-booking-note"},{"title":"Delete a booking note","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/bookings/{bookingId}/notes/{noteId}","href":"/api-reference/bookings/delete-a-booking-note"},{"title":"Update a booking note","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/bookings/{bookingId}/notes/{noteId}","href":"/api-reference/bookings/update-a-booking-note"},{"title":"List the reports filed on a booking","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/bookings/{bookingId}/reports","href":"/api-reference/bookings/list-the-reports-filed-on-a-booking"},{"title":"File one side's report on a booking","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/bookings/{bookingId}/reports","href":"/api-reference/bookings/file-one-sides-report-on-a-booking"}]},{"group":"Reviews","pages":[{"title":"List every review linked to a booking","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/bookings/{bookingId}/reviews","href":"/api-reference/reviews/list-every-review-linked-to-a-booking"},{"title":"Review a booking, in either direction","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/bookings/{bookingId}/reviews","href":"/api-reference/reviews/review-a-booking-in-either-direction"},{"title":"List reviews for a project (newest first); filter by supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/reviews","href":"/api-reference/reviews/list-reviews-for-a-project-newest-first;-filter-by-supplier"},{"title":"Create a supplier review (1–5 star rating with optional comment)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/reviews","href":"/api-reference/reviews/create-a-supplier-review-1–5-star-rating-with-optional-comment"},{"title":"List the reviews written about a client","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/clients/{clientId}/reviews","href":"/api-reference/reviews/list-the-reviews-written-about-a-client"},{"title":"Get a client's average rating and review count","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/clients/{clientId}/review-summary","href":"/api-reference/reviews/get-a-clients-average-rating-and-review-count"},{"title":"Get a supplier's average rating and review count","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/{supplierId}/review-summary","href":"/api-reference/reviews/get-a-suppliers-average-rating-and-review-count"}]},{"group":"Orders","pages":[{"title":"List orders by status, by payment method, or every order in a date range","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/orders","href":"/api-reference/orders/list-orders-by-status-by-payment-method-or-every-order-in-a-date-range"},{"title":"Create a new order","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/orders","href":"/api-reference/orders/create-a-new-order"},{"title":"Get an order by ID","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/orders/{orderId}","href":"/api-reference/orders/get-an-order-by-id"},{"title":"Soft-delete an order","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/orders/{orderId}","href":"/api-reference/orders/soft-delete-an-order"},{"title":"Update an order","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/orders/{orderId}","href":"/api-reference/orders/update-an-order"},{"title":"Get an order with its items","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/orders/{orderId}/aggregate","href":"/api-reference/orders/get-an-order-with-its-items"},{"title":"List orders for a client","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/clients/{clientId}/orders","href":"/api-reference/orders/list-orders-for-a-client"},{"title":"Change order status","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/orders/{orderId}/status","href":"/api-reference/orders/change-order-status"},{"title":"Add an item to an order","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/orders/{orderId}/items","href":"/api-reference/orders/add-an-item-to-an-order"},{"title":"Remove an order item","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/orders/{orderId}/items/{orderItemId}","href":"/api-reference/orders/remove-an-order-item"},{"title":"Update an order item quantity","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/orders/{orderId}/items/{orderItemId}","href":"/api-reference/orders/update-an-order-item-quantity"},{"title":"List the bookings created for a PACKAGE order item","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/orders/{orderId}/package-bookings","href":"/api-reference/orders/list-the-bookings-created-for-a-package-order-item"},{"title":"Create N package sessions atomically (or best-effort) from one PACKAGE order item","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/orders/{orderId}/package-bookings","href":"/api-reference/orders/create-n-package-sessions-atomically-or-best-effort-from-one-package-order-item"}]},{"group":"Suppliers","pages":[{"title":"List suppliers for a project, enriched with services and skills; filter by service/skill/region/point","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers","href":"/api-reference/suppliers/list-suppliers-for-a-project-enriched-with-services-and-skills;-filter-by-serviceskillregionpoint"},{"title":"Create a supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers","href":"/api-reference/suppliers/create-a-supplier"},{"title":"One supplier in full: profile, services, skills, locations, rating and working hours","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/suppliers/{supplierId}","href":"/api-reference/suppliers/one-supplier-in-full:-profile-services-skills-locations-rating-and-working-hours"},{"title":"Update a supplier; sync its service/skill mappings when arrays are supplied","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/projects/{projectId}/suppliers/{supplierId}","href":"/api-reference/suppliers/update-a-supplier;-sync-its-serviceskill-mappings-when-arrays-are-supplied"},{"title":"Soft-delete a supplier (cascade-removes its mappings and avatar)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/{supplierId}","href":"/api-reference/suppliers/soft-delete-a-supplier-cascade-removes-its-mappings-and-avatar"},{"title":"Add a service to a supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/{supplierId}/services/{serviceId}","href":"/api-reference/suppliers/add-a-service-to-a-supplier"},{"title":"Remove a service from a supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/{supplierId}/services/{serviceId}","href":"/api-reference/suppliers/remove-a-service-from-a-supplier"},{"title":"Add a skill to a supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/{supplierId}/skills/{skillId}","href":"/api-reference/suppliers/add-a-skill-to-a-supplier"},{"title":"Remove a skill from a supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/{supplierId}/skills/{skillId}","href":"/api-reference/suppliers/remove-a-skill-from-a-supplier"},{"title":"Get a presigned URL to upload a supplier avatar","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suppliers/{supplierId}/avatar/upload-url","href":"/api-reference/suppliers/get-a-presigned-url-to-upload-a-supplier-avatar"},{"title":"Confirm an uploaded avatar and attach it to the supplier","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/projects/{projectId}/suppliers/{supplierId}/avatar","href":"/api-reference/suppliers/confirm-an-uploaded-avatar-and-attach-it-to-the-supplier"},{"title":"Remove a supplier's avatar","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/suppliers/{supplierId}/avatar","href":"/api-reference/suppliers/remove-a-suppliers-avatar"}]},{"group":"Availability","pages":[{"title":"Find suppliers + suggested/open slots for a service, location and window","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/availability/search","href":"/api-reference/availability/find-suppliers-+-suggestedopen-slots-for-a-service-location-and-window"},{"title":"Generate clustered time slots from suppliers + engine config","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/availability/time-slots","href":"/api-reference/availability/generate-clustered-time-slots-from-suppliers-+-engine-config"},{"title":"Supplier-centric availability: paginated suppliers, each with open slots grouped by day","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/availability/suppliers","href":"/api-reference/availability/supplier-centric-availability:-paginated-suppliers-each-with-open-slots-grouped-by-day"},{"title":"Build a single-supplier N-session package slate (policy-driven), persisting suggestions","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/availability/package-slate","href":"/api-reference/availability/build-a-single-supplier-n-session-package-slate-policy-driven-persisting-suggestions"},{"title":"List a service's packages, each with a ready-to-book slate","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/availability/package-options","href":"/api-reference/availability/list-a-services-packages-each-with-a-ready-to-book-slate"}]},{"group":"Suggestions","pages":[{"title":"Reschedule a suggested slot to a new time (server-validated), refreshing its slate","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/suggestions/slots/{slotId}/reschedule","href":"/api-reference/suggestions/reschedule-a-suggested-slot-to-a-new-time-server-validated-refreshing-its-slate"}]},{"group":"Holds","pages":[{"title":"Hold supplier time during checkout — a single session, or a whole package slate","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/holds","href":"/api-reference/holds/hold-supplier-time-during-checkout-—-a-single-session-or-a-whole-package-slate"},{"title":"Read a hold — its status, its heldUntil, and the supplier time it claims","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/holds/{reservationId}","href":"/api-reference/holds/read-a-hold-—-its-status-its-helduntil-and-the-supplier-time-it-claims"},{"title":"Release a hold (HELD → RELEASED) — idempotent","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/holds/{reservationId}/release","href":"/api-reference/holds/release-a-hold-held-→-released-—-idempotent"},{"title":"Convert a hold into confirmed bookings (the idempotent purchase hook)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/holds/{reservationId}/convert","href":"/api-reference/holds/convert-a-hold-into-confirmed-bookings-the-idempotent-purchase-hook"}]},{"group":"Clients","pages":[{"title":"Onboard the authenticated client to a project","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/clients/me","href":"/api-reference/clients/onboard-the-authenticated-client-to-a-project"},{"title":"Update the authenticated client's contact details","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/clients/me","href":"/api-reference/clients/update-the-authenticated-clients-contact-details"},{"title":"Get the authenticated client's package credits","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/clients/me/credits","href":"/api-reference/clients/get-the-authenticated-clients-package-credits"},{"title":"Book sessions from the authenticated client's own package credit","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/clients/me/orders/{orderId}/package-bookings","href":"/api-reference/clients/book-sessions-from-the-authenticated-clients-own-package-credit"},{"title":"Add a service address to the caller's client profile","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/clients/me/addresses","href":"/api-reference/clients/add-a-service-address-to-the-callers-client-profile"},{"title":"Remove one of the caller's addresses","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/clients/me/addresses/{addressId}","href":"/api-reference/clients/remove-one-of-the-callers-addresses"},{"title":"Update one of the caller's addresses","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /v1/projects/{projectId}/clients/me/addresses/{addressId}","href":"/api-reference/clients/update-one-of-the-callers-addresses"},{"title":"Set the caller's default address","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/projects/{projectId}/clients/me/addresses/{addressId}/default","href":"/api-reference/clients/set-the-callers-default-address"}]},{"group":"Services","pages":[{"title":"List services for a project","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/services","href":"/api-reference/services/list-services-for-a-project"},{"title":"Create a new service","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/services","href":"/api-reference/services/create-a-new-service"},{"title":"Get a service by ID","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/services/{serviceId}","href":"/api-reference/services/get-a-service-by-id"},{"title":"Update a service","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/projects/{projectId}/services/{serviceId}","href":"/api-reference/services/update-a-service"},{"title":"Soft delete a service","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/services/{serviceId}","href":"/api-reference/services/soft-delete-a-service"},{"title":"Change service status","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/services/{serviceId}/status","href":"/api-reference/services/change-service-status"}]},{"group":"ServiceBusinessModels","pages":[{"title":"List business models for a service","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/services/{serviceId}/business-models","href":"/api-reference/servicebusinessmodels/list-business-models-for-a-service"},{"title":"Add a business model to a service","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/services/{serviceId}/business-models","href":"/api-reference/servicebusinessmodels/add-a-business-model-to-a-service"},{"title":"Update a business model","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/projects/{projectId}/services/{serviceId}/business-models/{businessModelId}","href":"/api-reference/servicebusinessmodels/update-a-business-model"},{"title":"Toggle business model active status","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/services/{serviceId}/business-models/{businessModelId}/status","href":"/api-reference/servicebusinessmodels/toggle-business-model-active-status"}]},{"group":"ServiceOfferings","pages":[{"title":"List offerings for a service","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/services/{serviceId}/offerings","href":"/api-reference/serviceofferings/list-offerings-for-a-service"},{"title":"Add an offering to a service","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/services/{serviceId}/offerings","href":"/api-reference/serviceofferings/add-an-offering-to-a-service"},{"title":"Get an offering","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}","href":"/api-reference/serviceofferings/get-an-offering"},{"title":"Update an offering","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}","href":"/api-reference/serviceofferings/update-an-offering"},{"title":"Soft delete an offering","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}","href":"/api-reference/serviceofferings/soft-delete-an-offering"},{"title":"Change offering status","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}/status","href":"/api-reference/serviceofferings/change-offering-status"}]},{"group":"ServicePackages","pages":[{"title":"List packages for an offering (storefront)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}/packages","href":"/api-reference/servicepackages/list-packages-for-an-offering-storefront"},{"title":"Create a sellable package (bundle) for an offering","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}/packages","href":"/api-reference/servicepackages/create-a-sellable-package-bundle-for-an-offering"},{"title":"List every package for a service (storefront discovery)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/services/{serviceId}/packages","href":"/api-reference/servicepackages/list-every-package-for-a-service-storefront-discovery"},{"title":"Get a package by id","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/packages/{packageId}","href":"/api-reference/servicepackages/get-a-package-by-id"},{"title":"Update a package","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /v1/projects/{projectId}/packages/{packageId}","href":"/api-reference/servicepackages/update-a-package"},{"title":"Change package status (rewrites the storefront sort key)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/packages/{packageId}/status","href":"/api-reference/servicepackages/change-package-status-rewrites-the-storefront-sort-key"}]},{"group":"Locations","pages":[{"title":"List locations for a project","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/locations","href":"/api-reference/locations/list-locations-for-a-project"},{"title":"Get a location by ID","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/locations/{locationId}","href":"/api-reference/locations/get-a-location-by-id"}]},{"group":"Skills","pages":[{"title":"List skills for a project","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/skills","href":"/api-reference/skills/list-skills-for-a-project"}]},{"group":"Transactions","pages":[{"title":"Record a manual (cash/external/comp) transaction against an order","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/orders/{orderId}/transactions","href":"/api-reference/transactions/record-a-manual-cashexternalcomp-transaction-against-an-order"},{"title":"List transactions (filter by order, client, or status)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/projects/{projectId}/transactions","href":"/api-reference/transactions/list-transactions-filter-by-order-client-or-status"},{"title":"Create a Stripe PaymentIntent for an order (client-side confirmation)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /v1/projects/{projectId}/orders/{orderId}/payment-intent","href":"/api-reference/transactions/create-a-stripe-paymentintent-for-an-order-client-side-confirmation"}]}]}]},{"tab":"Changelog","pages":[{"title":"Changelog","href":"/changelog/overview"}]}]},"basePath":"","title":"Report what your site showed: rendered searches, lists, impressions, clicks, profile views - MarketBox API","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-CiUHMMOm.js","snippetPresets-BgfXU7Bw.js","utils-DWvOwgy_.js","style-to-object-BY3JEAdk.js","utils-BN7RXSMJ.js","v4-DIgz8zy6.js","addUniqueKeysToSchema-CFw8bq89.js","conditional-requirements-CFM0id0Q.js","cloneDeep-CAwdfOU2.js","_Uint8Array-BJr8e-ZL.js","isObject-FP1Yky1u.js","ApiExamples-XX0UgMZK.js","usePlaygroundInputsStore-DXDFSa1V.js","shallow-CdX5aREi.js","isEqual-CoOaxexF.js","CodeSnippets-Cg2wpzWm.js","CodeSnippet-D_HwgQO_.js","getApiPlaygroundDisplay-CmCoerhe.js","Page-CVJ-f_k1.js","DynamicMarkdown-CQM9Bhbv.js","SectionHeading-DpbrP8nQ.js","icon-BPCgijHy.js","MethodPill-GQ8DuY0c.js","getPastedJson-Cb5mT31m.js","Check2Icon-a7bUI6e8.js","axios-CsQoIw0U.js","Markdown-CX2QY19L.js","AssistantPageLink-CY3bFglh.js","dist-Dl6_zDnT.js","lib-DMeTj1gb.js","lib-B8HbPgcC.js","katex-Dbtb6Wk7.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js"]}