Event schema

Every event sent to /v1/batch follows one of six schemas. All share a common base structure stamped by the SDK transport.

Common fields (all event types)

Field	Type	Required	Description
`type`	string	Yes	One of: `track`, `identify`, `page`, `screen`, `group`, `alias`
`messageId`	string	Yes	SDK-generated unique id (for dedup)
`timestamp`	ISO 8601 string	Yes	When the event occurred (SDK clock)
`anonymousId`	string	Yes	SDK-generated anonymous id
`userId`	string	Conditional	Your application user id. Set after `identify`.
`sessionId`	string	Yes	SDK-managed session id
`context`	object	No	Contextual metadata (see below).

Context object

Field	Type	Description
`context.ip`	string	Client IP address (stamped server-side)
`context.user_agent`	string	Browser/device user agent
`context.locale`	string	User locale (e.g., `en-IN`)
`context.page.url`	string	Current page URL
`context.page.referrer`	string	Referring URL
`context.device.type`	string	`mobile`, `desktop`, `tablet`
`context.campaign.source`	string	UTM source
`context.campaign.medium`	string	UTM medium
`context.campaign.name`	string	UTM campaign name

The Web SDK populates context automatically. For server-side events, include the fields you have.

track

Track a custom event — something the user did.


{
  "type": "track",
  "event": "order_completed",
  "messageId": "msg_01HXXXXX",
  "timestamp": "2026-05-27T10:30:00.000Z",
  "anonymousId": "anon_abc",
  "userId": "user_456",
  "sessionId": "sess_def",
  "properties": {
    "order_id": "ORD-123",
    "amount": 4999,
    "currency": "INR",
    "products": ["SKU-A", "SKU-B"]
  }
}

Field	Type	Required	Description
`event`	string	Yes	Event name (e.g., `order_completed`, `product_viewed`)
`properties`	object	No	Arbitrary key-value pairs describing the event

identify

Identify a user and set their traits.


{
  "type": "identify",
  "userId": "user_456",
  "anonymousId": "anon_abc",
  "messageId": "msg_01HXXXXX",
  "timestamp": "2026-05-27T10:30:00.000Z",
  "sessionId": "sess_def",
  "traits": {
    "name": "Priya Sharma",
    "email": "[email protected]",
    "plan": "pro",
    "company": "Acme Corp"
  }
}

Field	Type	Required	Description
`userId`	string	Yes	Your application user id
`traits`	object	No	Contact properties to set (merge-on-write)

identify is classified as PASSIVE for HAU billing — it stitches identity, it isn’t a user action. See MAU classification.

page

Track a web page view.


{
  "type": "page",
  "name": "Product Detail",
  "messageId": "msg_01HXXXXX",
  "timestamp": "2026-05-27T10:30:00.000Z",
  "anonymousId": "anon_abc",
  "userId": "user_456",
  "sessionId": "sess_def",
  "properties": {
    "product_id": "SKU-A",
    "category": "Electronics",
    "url": "https://store.example.com/p/SKU-A"
  }
}

Field	Type	Required	Description
`name`	string	No	Page name (e.g., “Home”, “Product Detail”)
`properties`	object	No	Additional page properties

screen

Track a mobile / SPA screen view. Same shape as page, but emitted by mobile SDKs or by web SPAs for in-place step transitions (e.g., storefront.cart).


{
  "type": "screen",
  "name": "storefront.cart",
  "messageId": "msg_01HXXXXX",
  "timestamp": "2026-05-27T10:30:00.000Z",
  "anonymousId": "anon_abc",
  "sessionId": "sess_def",
  "properties": { "step": "cart" }
}

group

Associate a user with a company or account.


{
  "type": "group",
  "userId": "user_456",
  "groupId": "company_789",
  "messageId": "msg_01HXXXXX",
  "timestamp": "2026-05-27T10:30:00.000Z",
  "anonymousId": "anon_abc",
  "sessionId": "sess_def",
  "traits": {
    "name": "Acme Corp",
    "industry": "Retail",
    "employees": 50
  }
}

Field	Type	Required	Description
`groupId`	string	Yes	The group/company identifier
`traits`	object	No	Group properties

alias

Merge an anonymous session with an identified user.


{
  "type": "alias",
  "userId": "user_456",
  "anonymousId": "anon_abc123",
  "messageId": "msg_01HXXXXX",
  "timestamp": "2026-05-27T10:30:00.000Z",
  "sessionId": "sess_def"
}

Field	Type	Required	Description
`userId`	string	Yes	The identified user id (destination)
`anonymousId`	string	Yes	The anonymous id to merge (source)

After aliasing, events from anon_abc123 are attributed to user_456. alias is also classified as PASSIVE for HAU billing — it’s identity stitching, not a user action.

What’s next

Event ingestion — the batch API endpoint
Receipt events — delivery status events
MAU classification — which events count toward billing