Understand event types and payload structure

Audience	How you'll use this article
Marketing teams	Understand which event types exist and what they represent.
Data teams	Validate event payloads and understand how events map to tables.
Engineering teams	Implement SDKs and ensure correct identity and schema usage.

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

The SDK and collector populate identifiers and timestamps; your application does not need to set every field itself.

Optional fields

context — SDK metadata and any context supplied by your application (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 (for example, 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.

Field	Javascript	iOS	Android	React Native	Description
app.name		✅	✅	✅	Name of the application.
app.version		✅	✅	✅	Version of the application.
app.build		✅	✅	✅	Build of the application.
app.namespace		✅	✅	✅	Bundle identifier or Android package name.
campaign.*	✅				Values from `utm_*` query parameters; `utm_campaign` maps to `campaign.name`.
amp.id	✅				Existing `_ga` cookie value, only when it starts with `amp`.
referrer.id, referrer.type	✅				Attribution from `btid`, `urid`, or a stored attribution cookie.
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.
instanceId		✅	✅	✅	UUID generated when the SDK initializes its context.
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. React Native collects this on Android only.
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	✅				Browser brands, versions, mobile status, and platform (Client Hints).
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.
Standalone iOS advertising identifiers require an added plugin or custom enrichment. The vendor ID in device.id is collected by default.
The standalone Android SDK automatically attempts advertising-ID collection when the Google Play Services AdvertisingIdClient class is present in the app. The core SDK does not bundle that dependency. It omits the advertising ID when limit-ad-tracking is enabled, but can still report adTrackingEnabled: false.
React Native collects device.id on iOS by default; Android requires collectDeviceId: true. Advertising identifiers require optional plugins.
Browser and iOS identify calls put traits at the event's top level, not in context.traits. Browser can also import traits from URL parameters and legacy cookies. See Browser user traits.
Standalone Android copies stored user traits, including the generated anonymousId and any supplied userId, into context.traits.
React Native does not automatically collect user traits. Its identify calls use top-level traits; context.traits starts as an empty object.
Outside context, the SDK generates and retains anonymousId unless one is supplied. userId is supplied by your application or the Browser QueryString API and retained for subsequent events; it is not inferred from the device.