> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/events
openapi: 3.0.0
info:
  title: MarketBox 2.0 Open API
  version: 1.0.0
  description: >-
    The MarketBox public API for building booking experiences. Core model:
    create an order, then draw its order items down into bookings. Single
    bookings reference an order item per service line; package bookings draw one
    PACKAGE item down across N sessions. To schedule a package, build a slate
    (POST /availability/package-slate) and book it by slateId (POST
    /orders/{orderId}/package-bookings). See the guides for end-to-end
    walkthroughs.
  contact:
    name: MarketBox support
servers:
  - url: https://apiv2.gomarketbox.com
    description: MarketBox Open API
security:
  - ApiKeyAuth: []
paths:
  /v1/projects/{projectId}/events:
    post:
      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).


        **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`.
      parameters:
        - 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
          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
        - 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.
          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:
              $ref: '#/components/schemas/SiteEventsBatch'
      responses:
        '202':
          description: 'The batch was read: what was accepted and what was not'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiteEventsAccepted'
        '400':
          description: 'Not a batch: no `events` array, or more than 500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: API key lacks `events:write` or cannot access this project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '413':
          description: The body is over 256 KB; nothing was read
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too many requests from this key; retry after a second
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '503':
          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:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    SiteEventsBatch:
      type: object
      properties:
        events:
          type: array
          items:
            type: object
            allOf:
              - $ref: '#/components/schemas/SiteEvent'
            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.
          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.
      required:
        - events
    SiteEventsAccepted:
      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
        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
        rejected:
          type: array
          items:
            $ref: '#/components/schemas/SiteEventRejection'
          description: The events not accepted, in batch order. Fix and resend only these.
      required:
        - accepted
        - duplicates
        - rejected
    ErrorMessage:
      type: object
      properties:
        code:
          type: string
          description: Stable machine-readable error code, e.g. NOT_FOUND.
        message:
          type: string
          description: Human-readable description of what went wrong.
        statusCode:
          type: integer
          description: The HTTP status code of this response.
        requestId:
          type: string
          description: >-
            The id of this request, also returned as the X-Request-Id header.
            Quote it in a support ticket.
      required:
        - code
        - message
        - statusCode
        - requestId
      example:
        code: NOT_FOUND
        message: Booking not found
        statusCode: 404
        requestId: a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10
    SiteEvent:
      oneOf:
        - $ref: '#/components/schemas/SiteEventOpportunity'
        - $ref: '#/components/schemas/SiteEventImpression'
        - $ref: '#/components/schemas/SiteEventClick'
        - $ref: '#/components/schemas/SiteEventProfileView'
        - $ref: '#/components/schemas/SiteEventCoverageMiss'
        - $ref: '#/components/schemas/SiteEventSearchRendered'
      discriminator:
        propertyName: type
        mapping:
          opportunity: '#/components/schemas/SiteEventOpportunity'
          impression: '#/components/schemas/SiteEventImpression'
          click: '#/components/schemas/SiteEventClick'
          profile_view: '#/components/schemas/SiteEventProfileView'
          coverage_miss: '#/components/schemas/SiteEventCoverageMiss'
          search.rendered: '#/components/schemas/SiteEventSearchRendered'
      description: >-
        One site event. `type` picks the shape; the fields every type shares are
        listed on each.
    SiteEventRejection:
      type: object
      properties:
        index:
          type: integer
          description: The position of the rejected element in `events`, 0-based.
          example: 3
        eventId:
          type: string
          nullable: true
          description: Its `eventId`, or null when the element had none.
          example: clk_9d7e1f0a-2b4c-4d8e-9f3a-6b5c4d3e2f1a
        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
        message:
          type: string
          description: What was wrong, for a person.
          example: supplier sup_01kv60qh3m7wznp8s0d2rk9abc is not in this project
      required:
        - index
        - eventId
        - code
        - message
    SiteEventOpportunity:
      type: object
      properties:
        type:
          type: string
          enum:
            - opportunity
          example: opportunity
          description: 'A list that includes suppliers was drawn: one event per list render.'
        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
        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'
        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
        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
        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
        serviceId:
          type: string
          minLength: 1
          maxLength: 128
          description: The service the list or search was for, when there was one.
          example: srv_01kv60qg12e82acr78edfnjhvv
        locale:
          type: string
          minLength: 2
          maxLength: 16
          description: The page locale, as a BCP 47 tag.
          example: en-CA
        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
        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
        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
        surface:
          type: string
          enum:
            - home
            - results
            - listing
            - site_search
            - profile
            - widget
            - assistant
            - other
          description: Where on the site the list was drawn.
          example: results
        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
              position:
                type: integer
                minimum: 0
                description: >-
                  0-based rank in the list as drawn (the same number a search
                  response returns).
                example: 0
            required:
              - supplierId
              - position
            additionalProperties: false
          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
      required:
        - type
        - eventId
        - occurredAt
        - surface
        - suppliers
      additionalProperties: false
    SiteEventImpression:
      type: object
      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.
        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
        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'
        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
        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
        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
        serviceId:
          type: string
          minLength: 1
          maxLength: 128
          description: The service the list or search was for, when there was one.
          example: srv_01kv60qg12e82acr78edfnjhvv
        locale:
          type: string
          minLength: 2
          maxLength: 16
          description: The page locale, as a BCP 47 tag.
          example: en-CA
        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
        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
        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
        listId:
          type: string
          minLength: 1
          maxLength: 128
          description: The `eventId` of the `opportunity` this card belongs to.
          example: lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b
        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
        position:
          type: integer
          minimum: 0
          description: >-
            0-based rank in the list as drawn (the same number a search response
            returns).
          example: 0
      required:
        - type
        - eventId
        - occurredAt
        - listId
        - supplierId
        - position
      additionalProperties: false
    SiteEventClick:
      type: object
      properties:
        type:
          type: string
          enum:
            - click
          example: click
          description: The client opened a supplier's profile or card from a list.
        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
        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'
        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
        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
        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
        serviceId:
          type: string
          minLength: 1
          maxLength: 128
          description: The service the list or search was for, when there was one.
          example: srv_01kv60qg12e82acr78edfnjhvv
        locale:
          type: string
          minLength: 2
          maxLength: 16
          description: The page locale, as a BCP 47 tag.
          example: en-CA
        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
        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
        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
        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
        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
        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
      required:
        - type
        - eventId
        - occurredAt
        - supplierId
      additionalProperties: false
    SiteEventProfileView:
      type: object
      properties:
        type:
          type: string
          enum:
            - profile_view
          example: profile_view
          description: A supplier's profile page loaded, from anywhere.
        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
        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'
        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
        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
        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
        serviceId:
          type: string
          minLength: 1
          maxLength: 128
          description: The service the list or search was for, when there was one.
          example: srv_01kv60qg12e82acr78edfnjhvv
        locale:
          type: string
          minLength: 2
          maxLength: 16
          description: The page locale, as a BCP 47 tag.
          example: en-CA
        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
        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
        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
        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
        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
      required:
        - type
        - eventId
        - occurredAt
        - supplierId
        - referrerClass
      additionalProperties: false
    SiteEventCoverageMiss:
      type: object
      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.
        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
        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'
        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
        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
        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
        serviceId:
          type: string
          minLength: 1
          maxLength: 128
          description: The service the list or search was for, when there was one.
          example: srv_01kv60qg12e82acr78edfnjhvv
        locale:
          type: string
          minLength: 2
          maxLength: 16
          description: The page locale, as a BCP 47 tag.
          example: en-CA
        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
        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
        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
      required:
        - type
        - eventId
        - occurredAt
      additionalProperties: false
    SiteEventSearchRendered:
      type: object
      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`.
        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
        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'
        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
        searchId:
          type: string
          minLength: 1
          maxLength: 128
          description: The `searchId` of the search response whose results were drawn.
          example: srch_01k7q3x9h4e8rb2d6m0z5a7c1n
        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
        serviceId:
          type: string
          minLength: 1
          maxLength: 128
          description: The service the list or search was for, when there was one.
          example: srv_01kv60qg12e82acr78edfnjhvv
        locale:
          type: string
          minLength: 2
          maxLength: 16
          description: The page locale, as a BCP 47 tag.
          example: en-CA
        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
        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
        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
        surface:
          type: string
          enum:
            - home
            - results
            - listing
            - site_search
            - profile
            - widget
            - assistant
            - other
          description: Where on the site the list was drawn.
          example: results
        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
              position:
                type: integer
                minimum: 0
                description: >-
                  0-based rank in the list as drawn (the same number a search
                  response returns).
                example: 0
            required:
              - supplierId
              - position
            additionalProperties: false
          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
      required:
        - type
        - eventId
        - occurredAt
        - searchId
        - surface
        - suppliers
      additionalProperties: false
  securitySchemes:
    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`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.