Understand event types and payload structure

Overview

Hightouch Events uses a standard event structure for identifying users, tracking actions, and recording page and screen views, while letting your team control event structure and identity behavior. This article defines the event tracking specification used by Hightouch:

Supported event types
Required and optional fields
Identity behavior across anonymous and known users
Shared payload structure
Example JSON payloads

Use this guide when implementing SDKs, reviewing event data, or validating incoming events.

Supported event types

Hightouch supports the following event types:

Event type	Purpose
`identify`	Identify a known user and set user-level traits
`track`	Record an action a user performed
`page`	Record a browser page view
`screen`	Record a mobile app screen view
`group`	Associate a user with a group or account

Each event type builds on a shared base structure and adds its own required fields.

Shared event structure

All event types share a common base structure, so Hightouch can validate, govern, and activate events consistently across destinations.

Required fields

type — The event type (identify, track, page, screen, group)
messageId — A unique identifier for the event
At least one identifier: anonymousId or userId
originalTimestamp — When the event occurred
sentAt — When the event was sent by the SDK or API

Optional fields

context — Automatically collected metadata (device, OS, SDK version, etc.)
integrations — Destination-specific flags
traits or properties — Metadata attached to the event:
- Traits describe the user (for example, email or plan)
- Properties describe the action or context (for example, price or product ID)

Identify events

Identify events capture data about who a user is. They are used to:

Associate anonymous activity with a known user
Set or update user-level traits
Link events across devices and sessions

For example, you might use Identify events to power follow-up email campaigns, segment users by location or plan, or link anonymous activity to authenticated behavior. Users often generate events before they log in or sign up. During this time, events are associated with an anonymousId. When you later send an Identify event that includes both a userId and the same anonymousId, subsequent events from that device include both identifiers. You can then join earlier anonymous-only events to the known user in your warehouse models using the shared anonymousId.

Components of Identify events

anonymousId
A device- or browser-level identifier generated by the SDK to associate events from the same user before they are identified. This value is included automatically in other event types (e.g., Track events).
An anonymousId typically persists across multiple sessions on the same device or browser.
userId
A stable, persistent identifier for a known user (for example, it’s common to use an ID generated by your database). Avoid using mutable values such as email addresses.
traits
Optional user attributes, such as email, name, or age.

Example identify event payload

{
  "type": "identify",
  "messageId": "111e984d-c93c-444c-b29c-f499a117c500",
  "traits": {
    "email": "kevin@hightouch.io"
  },
  "anonymousId": "ce576487-95f9-4262-9315-2c7942b061c8",
  "userId": "123",
  "originalTimestamp": "2023-09-22T18:05:47.063Z",
  "sentAt": "2023-09-22T18:05:47.064Z"
}

Track events

Track events capture data about what a user did, such as completing a purchase or clicking a button. Additional details about the action are included in the properties object. For example, for a Purchase Complete event, you may want to include the product ids of the purchased products. When events are stored in the warehouse, the event field is used to generate table names in the warehouse. Additionally, the properties field is autoconverted into columns in the warehouse.

Example track event payload

{
  "type": "track",
  "messageId": "7b1e2872-4ebb-4779-b9ad-e7aa1a8eab82",
  "anonymousId": "ce576487-95f9-4262-9315-2c7942b061c8",
  "userId": "123",
  "event": "Purchase completed",
  "properties": {
    "cart_total": 24.99
  },
  "originalTimestamp": "2023-09-22T18:12:00.584Z",
  "sentAt": "2023-09-22T18:12:00.585Z"
}

Page events

Page events track the webpages users interact with. In most situations, you should automatically call the page load event when a page is loaded. For single-page applications, trigger page events on route changes.

Example page event payload

{
  "type": "page",
  "messageId": "bb9fcbbd-9e19-4bfd-a726-7b1e7e44f8ba",
  "anonymousId": "ce576487-95f9-4262-9315-2c7942b061c8",
  "userId": "123",
  "properties": {
    "title": "Home"
  },
  "originalTimestamp": "2023-09-22T18:05:47.061Z",
  "sentAt": "2023-09-22T18:05:47.063Z"
}

Screen events

Screen events are the equivalent of page views for mobile apps. Like page events, you should automatically call the screen event when a mobile screen view is loaded.

Example screen event payload

{
  "type": "screen",
  "messageId": "bb9fcbbd-9e19-4bfd-a726-7b1e7e44f8ba",
  "anonymousId": "ce576487-95f9-4262-9315-2c7942b061c8",
  "userId": "123",
  "properties": {
    "title": "Home"
  },
  "originalTimestamp": "2023-09-22T18:05:47.061Z",
  "sentAt": "2023-09-22T18:05:47.063Z"
}

Group events

Group events let you associate users with a larger group. For example, a user may be part of an organization, or family. The traits field is optional, and can include information on traits on the group. For example, if linking a user to a company, you may include traits on the company such as the company size or location.

Example group event payload

{
  "type": "group",
  "messageId": "d87596da-5f1e-40f4-a28a-7099290548b7",
  "anonymousId": "ce576487-95f9-4262-9315-2c7942b061c8",
  "userId": "123",
  "groupId": "456",
  "traits": { "company_name": "Hightouch" },
  "originalTimestamp": "2023-09-22T18:46:23.098Z",
  "sentAt": "2023-09-22T18:46:23.099Z"
}

Automatically captured fields

Hightouch SDKs automatically populate common context fields about the device, environment, and session. The table below shows which fields are captured by each SDK.

CONTEXT FIELD	Javascript	iOS	Android	Description
app.name		✅	✅	Name of the application.
app.version		✅	✅	Version of the application.
app.build		✅	✅	Build of the application.
campaign.name	✅			Name of the campaign.
campaign.source	✅			Source of the campaign.
campaign.medium	✅			Medium of the campaign.
campaign.term	✅			Term of the campaign.
campaign.content	✅			Content of the campaign.
device.type		✅	✅	Type of the device.
device.id		✅	✅	ID of the device.
device.advertisingId		✅	✅	Advertising ID of the device.
device.adTrackingEnabled		✅	✅	If ad tracking is enabled on the device.
device.manufacturer		✅	✅	Manufacturer of the device.
device.model		✅	✅	Model of the device.
device.name		✅	✅	Name of the device.
library.name	✅	✅	✅	Name of the library.
library.version	✅	✅	✅	Version of the library.
ip	✅	✅	✅	Current user’s IP address.
locale	✅	✅	✅	Locale string of the user.
network.bluetooth			✅	Bluetooth information.
network.carrier		✅	✅	Carrier information about the network connection.
network.cellular		✅	✅	Cellular information about the network connection.
network.wifi		✅	✅	WiFi information about the network connection.
os.name		✅	✅	Name of the operating system.
os.version		✅	✅	Version of the operating system.
page.path	✅			Path of the current page in the browser.
page.referrer	✅			Referrer of the current page in the browser.
page.search	✅			Search of the current page in the browser.
page.title	✅			Title of the current page in the browser.
page.url	✅			URL of the current page in the browser.
screen.density			✅	Density of the device’s screen.
screen.height		✅	✅	Height of the device’s screen.
screen.width		✅	✅	Width of the device’s screen.
sessionId	✅	✅	✅	Identifier for the current session. Mobile SDKs use epoch milliseconds.
sessionStart	✅	✅	✅	Present and `true` only on the first event of a session.
session.sessionId		✅	✅	Same value as `context.sessionId`.
session.sessionIndex		✅	✅	Per-device lifetime session counter. Starts at 0. Resets only on uninstall.
session.sessionStart		✅	✅	Present and `true` only on the first event of a session.
session.eventIndex		✅	✅	0-based index of the event within the session.
session.previousSessionId		✅	✅	Previous session ID, or null on the first session.
session.firstEventId		✅	✅	UUID (`messageId`) of the session’s first event.
session.firstEventTimestamp		✅	✅	ISO 8601 timestamp for when the session began.
traits		✅	✅	Traits of the user.
userAgent	✅		✅	User agent of the device making the request.
userAgentData	✅			Information about the user’s timezone.
timezone		✅	✅	Information about the user’s timezone.

IP Addresses are captured by Hightouch’s servers when a message is received for client-side events and is not captured by Hightouch’s libraries.
userAgentData is only collected if the Client Hints API is available on the browser.
The Flutter and React Native SDKs capture the same session fields as iOS and Android. Session tracking is enabled by default. See iOS, Android, Flutter, and React Native for timeout configuration.

Get started

Marketing

Data platform

Manage

Resources

API reference

Understand event types and payload structure

Overview

Supported event types

Shared event structure

Required fields

Optional fields

Identify events

Components of Identify events

Example identify event payload

Track events

Example track event payload

Page events

Example page event payload

Screen events

Example screen event payload

Group events

Example group event payload

Automatically captured fields

​Overview

​Supported event types

​Shared event structure

​Required fields

​Optional fields

​Identify events

​Components of Identify events

​Example identify event payload

​Track events

​Example track event payload

​Page events

​Example page event payload

​Screen events

​Example screen event payload

​Group events

​Example group event payload

​Automatically captured fields

Overview

Supported event types

Shared event structure

Required fields

Optional fields

Identify events

Components of Identify events

Example identify event payload

Track events

Example track event payload

Page events

Example page event payload

Screen events

Example screen event payload

Group events

Example group event payload

Automatically captured fields