started_session
A visitor's session began. Carries the touch: how they arrived, and with which consent.
Derived by the service from the first call of a session (context.sessionStart), not sent by the SDK as such; a backend may send one for a session it knows about. The utm, click_ids, landing_url and referrer fields are the raw material of the touch block on later orders.
| Sent with | browser, server keys (see write keys) |
| Mode | strict: exactly the declared fields; an undeclared key, a wrong type or a missing required key quarantines the event |
| Version | 1 (_schema_version on the stored row) |
| State | active |
| Required fields | session_id |
| Revenue | none: the revenue block is refused |
| Identity evidence | none |
| Before consent | no |
Fields
The activity's own fields, sent as features. Identifier and attribute fields are moved out of features by the processor; see identifiers and attributes.
| Field | Type | Required | What happens to it | Meaning |
|---|---|---|---|---|
click_ids | object of string | no | stays in features | Ad click ids read from the address or a cookie, by platform key (gclid, fbclid, …), as /v1/config lists them. Read only with ads consent. |
consent | object | no, may be null | stays in features | The consent snapshot at the time: analytics, ads and personalisation, each true or false. |
consent.ads | boolean | no, may be null | stays in features | Whether ads consent was given. |
consent.analytics | boolean | no, may be null | stays in features | Whether analytics consent was given. |
consent.personalisation | boolean | no, may be null | stays in features | Whether personalisation consent was given. |
landing_url | string | no, may be null | stays in features | The first page of the session, as the visitor arrived on it, query included. |
referrer | string | no, may be null | stays in features | The page the visitor came from, as the browser reported it. |
session_id | string | yes | stays in features | The browser session, as the SDK assigns it (context.sessionId on calls). Joins page views to the session that started them. |
utm | object | no, may be null | stays in features | The campaign parameters as typed in the address: source, medium, campaign, term, content. |
utm.campaign | string | no, may be null | stays in features | utm_campaign as typed. |
utm.content | string | no, may be null | stays in features | utm_content as typed. |
utm.medium | string | no, may be null | stays in features | utm_medium as typed. |
utm.source | string | no, may be null | stays in features | utm_source as typed. |
utm.term | string | no, may be null | stays in features | utm_term as typed. |
Example
One activity in a batch to POST /v1/activities, with debug so the answer says what the processor made of it. The envelope page explains every top-level field.
{
"batch": [
{
"activity_id": "0192f1a4-4907-758d-8000-490758d80000",
"activity": "started_session",
"ts": "2026-10-17T20:00:00+02:00",
"anonymous_customer_id": "evx_web_8f21c0",
"features": {
"click_ids": {
"gclid": "Cj0KCQjw"
},
"consent": {
"analytics": true,
"ads": false,
"personalisation": false
},
"landing_url": "https://summerfest.nl/?utm_source=newsletter&utm_medium=email&utm_campaign=early-bird",
"referrer": "https://www.google.com/",
"session_id": "s_01M4XVBYC3FGXCPFRZEPGV20RZ",
"utm": {
"source": "newsletter",
"medium": "email",
"campaign": "early-bird",
"term": null,
"content": null
}
}
}
],
"debug": true
}
Try it
Sends this request from your browser. The key and the endpoint are kept in this browser only.
Versions
| Version | Mode | Key classes | Change |
|---|---|---|---|
| 1 (current) | strict | browser, server | first version |
A published version never changes; a change is a new version, and every stored row says which version it was checked against.