Events HTTP API

This is the endpoint the tracker sends its events to. It is documented for debugging, for proxies and for custom browser clients. On a website, use the tracker: it adds the page context, retries failed requests and handles everything else on this page for you.

Built for browsers

Visitors and sessions are identified from the request's IP and user agent, and server, bot and private-network traffic is filtered out. Events sent from your back end would therefore be attributed to your server, or dropped. To send data from your back end, such as transactional emails, use the Server API.

Request

HTTP

POST https://tracker.sublimanalytics.com/api/v2/events
Content-Type: application/json
X-Project: YOUR_PROJECT_ID

JSON

{
  "n": "appointment_booked",
  "u": "https://example.com/booking/confirmed",
  "d": "example.com",
  "l": "fr-FR",
  "p": { "service": "piercing" },
  "amount": 45,
  "currency": "EUR"
}

Headers

Header	Description
`X-Project`	Required. Your project ID.
`X-Workspace`	Optional. Alone, the project is resolved from the site's domain (beta).
`Content-Type`	`application/json`

Body fields

Field	Type	Description
`n`	`string`	Required. Event name: `page_view`, `engagement` or any custom name.
`u`	`string`	Full page URL.
`d`	`string`	Hostname of the page.
`r`	`string`	Referrer (pageviews).
`t`	`string`	Page title (pageviews).
`l`	`string`	Browser language, such as `fr-FR`.
`w`, `h`	`number`	Viewport width and height (pageviews).
`sw`, `sh`	`number`	Screen width and height (pageviews).
`sd`	`number`	Scroll depth, in % (`engagement`).
`e`	`number`	Engaged time, in ms (`engagement`).
`p`	`object`	Properties. Values are stored as text; keep them flat.
`amount`	`number`	Revenue amount.
`currency`	`string`	ISO 4217 currency of `amount`.

The event's time is the moment the server receives it.

Responses

Status	Body	Meaning
`202`	`{"sv": 12}`	Accepted. `sv` is the project settings version, used by the tracker to refresh its cached settings.
`400`	`{"error": "…"}`	Invalid JSON, missing or unknown project.
`403`	`{"error": "domain not allowed"}`	The project's domain protection rejected the page's domain.
`503`	`{"error": "event queue full"}`	Temporarily overloaded. The tracker retries such events later.

Other endpoints used by the tracker

Endpoint	Purpose
`GET /api/v2/project/{projectId}/settings`	Project settings: cart and thank-you URLs, dataLayer configuration.
`POST /api/v2/replay`	Session replay batches.