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 provides a standardized way to collect user traits and user behavior across your applications, while allowing teams to 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. This ensures events can be validated, governed, and activated 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 Payload for Identify Event

{
  "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 Payload for Track Event

{
  "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 Payload for Page Event

{
  "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 Payload for Screen Event

{
  "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 Payload for Group Event

{
  "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.
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.