> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Understand event types and payload structure

> Learn how Hightouch Events structures identify, track, page, screen, and group events—including required fields, identity behavior, and example payloads.

## 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-events) | Identify a known user and set user-level traits |
| [`track`](#track-events) | Record an action a user performed |
| [`page`](#page-events) | Record a browser page view |
| [`screen`](#screen-events) | Record a mobile app screen view |
| [`group`](#group-events) | 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

```json theme={null}
{
  "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](https://docs.hightouch.com/events/warehouse-schema.md#per-event-tables) in the warehouse. Additionally, the
`properties` field is autoconverted into
[columns](https://docs.hightouch.com/events/warehouse-schema.md#per-event-tables) in the warehouse.

#### Example track event payload

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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](https://docs.hightouch.com/events/sdks/ios.md#session-tracking), [Android](https://docs.hightouch.com/events/sdks/android.md#session-tracking), [Flutter](https://docs.hightouch.com/events/sdks/flutter.md#session-tracking), and [React Native](https://docs.hightouch.com/events/sdks/react-native.md#session-tracking) for timeout configuration.