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

# Event Schema

> Welcome to the Userpilot Event Data Schema documentation! This guide provides a comprehensive overview of the structure, attributes, and relationships of.

Welcome to the Userpilot Event Data Schema documentation! This guide provides a comprehensive overview of the structure, attributes, and relationships of events exported from Userpilot. It is designed to help data analysts, engineers, and business users understand and utilize Userpilot event data for integration, analytics, and reporting purposes.

Below, you'll find detailed explanations of each event field, example payloads, and best practices for working with Userpilot data in your own systems.

***

## Event Structure

| **Attribute**       | **Type**       | **Description**                                                                                                                                     |
| ------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `app_token`         | String         | Unique identifier for the app.                                                                                                                      |
| `event_type`        | String         | Type of event (`identify_user`, `identify_company`, `interaction`, `track`, `track_feature`, `page_view`, `session_start`).                         |
| `event_name`        | String         | Name of the event. For some types, this is empty or contains details (see below).                                                                   |
| `user_id`           | String         | Unique identifier for the user (for `identify_user` events).                                                                                        |
| `company_id`        | String         | Unique identifier for the company (for `identify_company` events).                                                                                  |
| `source`            | String         | Source of the event (`web-client`, `backend-http`, `backend-hubspot`, `backend-salesforce`, `backend-segment`).                                     |
| `inserted_at`       | DateTime (UTC) | Timestamp of the event (microsecond precision).                                                                                                     |
| `internal_event_id` | String         | Unique identifier calculated using xxHash64 of the composite key (`app_token`, `event_type`, `event_name`, `user_id`, `company_id`, `inserted_at`). |
| `hostname`          | String         | Hostname where the event took place.                                                                                                                |
| `pathname`          | String         | Page path where the event occurred.                                                                                                                 |
| `screen_width`      | Integer        | User's screen width (px).                                                                                                                           |
| `screen_height`     | Integer        | User's screen height (px).                                                                                                                          |
| `device_type`       | String         | Device type (`desktop`, `mobile`, etc.).                                                                                                            |
| `user_agent`        | String         | Browser's user agent string.                                                                                                                        |
| `operating_system`  | String         | User's operating system.                                                                                                                            |
| `browser`           | String         | Browser name (e.g., `Chrome`).                                                                                                                      |
| `browser_language`  | String         | Browser language setting.                                                                                                                           |
| `session`           | String         | Session number (for SDK events, auto-updated for `web-client`).                                                                                     |
| `country_code`      | String         | 2-letter country code.                                                                                                                              |
| `metadata`          | Object         | The attributes object varies depending on the `event_type` (see below).                                                                             |

### Internal Event ID

The `internal_event_id` is a unique identifier for each event, calculated using the xxHash64 algorithm on a composite key consisting of the following fields:

* `app_token`
* `event_type`
* `event_name`
* `user_id`
* `company_id`
* `inserted_at`

This identifier provides a deterministic way to uniquely identify events based on their core attributes, which is useful for deduplication and event tracking across systems.

### Event Name & Type

The `event_name` field tracks the name of the event and varies depending on the `event_type`:

* **`For identify_user, identify_company, session_start, and page_view events:`** This field will be empty.
* **`For track events:`** The value will represent the name of the event being passed programmatically or through the button-tracking feature.
* **`For track_feature events:`** The value will contain the `id` of the tracked feature tag.
* **`For interaction events:`**

  * The format is `{entity_type}:{entity_id}:{entity_interaction_status}`
  * Example: `checklist:2:SEEN`, `experience:448:DISMISSED`, `resource_center:1:ENGAGED`, `experiment:9:SEEN`.

  <Note>
    When a flow is part of an experiment, both `experiment:*` and `experience:*` events are generated to track experiment participation and flow interaction respectively.
  </Note>

***

### Source

The `source` field indicates where the event was captured. The default value is `web-client`, but it can vary depending on the source of the event:

* **web-client**: Captured through the web SDK.
* **backend-http**: Captured via HTTP endpoints.
* **backend-hubspot**: Captured through the HubSpot integration.
* **backend-salesforce**: Captured through the Salesforce integration.
* **backend-segment**: Captured through SegmentIO integration.

***

### Attributes Schema

The `metadata` field varies depending on the event type:

* **`For identify_user, identify_company, and track events:`** This field will contain custom attributes passed during the event tracking.
* **`For page_view, session_start and track_feature events:`** This field will be an empty object.
* **`For interaction events:`** Attributes vary based on the engagement entity type and provide specific interaction details (see below).

***

## Interaction Attributes

Below are common interaction events and the relevant attributes associated with each.

### Surveys (`survey_module` events)

| **Attribute**     | **Type** | **Description**                                                                   |
| ----------------- | -------- | --------------------------------------------------------------------------------- |
| `feedback`        | String   | Feedback provided by the user, often a unique identifier or actual feedback text. |
| `interaction_id`  | String   | Unique ID of the survey module (e.g., `survey_module_49`).                        |
| `is_dismissed`    | String   | Indicates whether the survey was dismissed by the user (`1` for yes, `0` for no). |
| `parent_id`       | String   | The ID of the parent survey.                                                      |
| `status`          | String   | Current status of the survey interaction (e.g., `COMPLETED`, `DISMISSED`).        |
| `survey_question` | String   | The question presented to the user.                                               |
| `variant`         | String   | Survey type (e.g., `multiple_choice`, `open_text`).                               |

**Example:**

```json theme={null}
{
  "event_name": "survey_module:49:COMPLETED",
  "attributes": {
    "feedback": "318b72c9-b1ad-4bf6-854b-26d32ac9d281",
    "interaction_id": "survey_module_49",
    "is_dismissed": "0",
    "parent_id": "survey_13",
    "status": "COMPLETED",
    "survey_question": "",
    "variant": "multiple_choice"
  }
}
```

### Checklists (`checklist` and `checklist_task` events)

| **Attribute**    | **Type** | **Description**                                                                              |
| ---------------- | -------- | -------------------------------------------------------------------------------------------- |
| `interaction_id` | String   | Unique ID of the checklist or checklist task (e.g., `checklist_10`).                         |
| `is_dismissed`   | String   | Indicates whether the checklist or task was dismissed by the user (`1` for yes, `0` for no). |
| `parent_id`      | String   | The ID of the parent checklist, if applicable.                                               |
| `status`         | String   | Status of the checklist interaction (e.g., `SEEN`, `ENGAGED`).                               |

**Example:**

```json theme={null}
{
  "event_name": "checklist:10:SEEN",
  "attributes": {
    "interaction_id": "checklist_10",
    "is_dismissed": "",
    "parent_id": "",
    "status": "SEEN"
  }
}
```

### Resource Center and Articles (`resource_center`, `resource_center_article` events)

| **Attribute**    | **Type** | **Description**                                                                                    |
| ---------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `article_title`  | String   | Title of the article the user engaged with.                                                        |
| `article_url`    | String   | URL of the article.                                                                                |
| `interaction_id` | String   | Unique ID for the resource center interaction or article (e.g., `resource_center_article_6FAA69`). |
| `is_dismissed`   | String   | Indicates if the resource center or article interaction was dismissed.                             |
| `parent_id`      | String   | The ID of the parent resource center entity (if applicable).                                       |
| `status`         | String   | Status of the interaction (e.g., `ENGAGED`).                                                       |

**Example:**

```json theme={null}
{
  "event_name": "resource_center_article:6FAA69EBAFEEDF5E641ACF6D52847FC98AC44437591FC39D8BE67BDCF4570023:ENGAGED",
  "attributes": {
    "article_title": "How to Delete a Flow - Userpilot Knowledge Base",
    "article_url": "https://docs.userpilot.com/",
    "interaction_id": "resource_center_article_6FAA69EBAFEEDF5E641ACF6D52847FC98AC44437591FC39D8BE67BDCF4570023",
    "is_dismissed": "0",
    "parent_id": "resource_center_1",
    "status": "ENGAGED"
  }
}
```

### NPS Events

| **Attribute**        | **Type** | **Description**                                                                |
| -------------------- | -------- | ------------------------------------------------------------------------------ |
| `feedback`           | String   | Feedback provided by the user (can be text or a unique ID).                    |
| `follow_up_question` | String   | A follow-up question posed to the user after providing the NPS score.          |
| `interaction_id`     | String   | Unique ID for the NPS interaction (e.g., `nps_1`).                             |
| `score`              | String   | NPS score given by the user (typically between 0 and 10).                      |
| `status`             | String   | Status of the NPS interaction (e.g., `SUBMITTED_FEEDBACK`, `SUBMITTED_SCORE`). |
| `survey_question`    | String   | The specific NPS question posed to the user.                                   |
| `submission_id`      | String   | Unique identifier for the NPS submission.                                      |

**Example:**

```json theme={null}
{
  "event_name": "nps:1:SUBMITTED_FEEDBACK",
  "attributes": {
    "feedback": "Great tool, highly recommended!",
    "follow_up_question": "Is there anything else we can improve?",
    "interaction_id": "nps_1",
    "score": "9",
    "status": "COMPLETED",
    "submission_id": "2024-05-02",
    "survey_question": "How likely is it that you would recommend us to a friend or colleague?"
  }
}
```

### Flow and Flow Steps (`experience`, `experience_step` events)

| **Attribute**     | **Type** | **Description**                                                          |
| ----------------- | -------- | ------------------------------------------------------------------------ |
| `interaction_id`  | String   | Unique ID of the experience or experience step (e.g., `experience_493`). |
| `is_dismissed`    | String   | Indicates if the experience was dismissed (`1` for yes, `0` for no).     |
| `status`          | String   | The status of the experience (e.g., `COMPLETED`, `DISMISSED`).           |
| `total_dismissed` | String   | The total number of times the experience was dismissed by the user.      |

**Example:**

```json theme={null}
{
  "event_name": "experience:493:DISMISSED",
  "attributes": {
    "interaction_id": "experience_493",
    "is_dismissed": "1",
    "status": "DISMISSED",
    "total_dismissed": "1"
  }
}
```

<Note>
  **Flows in Experiments:** When a flow is part of a test experiment, the system generates BOTH `experiment:*` and `experience:*` events:

  * `experiment:*` events track experiment participation and variant assignment
  * `experience:*` events track flow interaction
</Note>

### Experiments (`experiment` events)

When flows are used testing experiments, Userpilot tracks experiment participation through dedicated experiment events. These events capture which variant (test group) a user was assigned to.

| **Attribute**      | **Type** | **Description**                                                                                   |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------- |
| `interaction_id`   | String   | Unique ID of the experiment (e.g., `experiment_9`).                                               |
| `is_dismissed`     | String   | Indicates whether the experiment interaction was dismissed by the user (`1` for yes, `0` for no). |
| `never_show_again` | String   | Indicates if the user chose to never see this again (`1` for yes, `0` for no).                    |
| `status`           | String   | Current status of the experiment interaction (e.g., `SEEN`, `COMPLETED`, `DISMISSED`).            |
| `total_dismissed`  | String   | The total number of times the experiment was dismissed by the user.                               |
| `variant`          | String   | The experiment group the user was assigned to. Contains the variant name (A, B, or C).            |

**Variant Values:**

The `variant` attribute indicates which test group the user was assigned to. Possible values are "A", "B", or "C" depending on the experiment type (Controlled A/B Test, Head-to-Head A/B Test, or Controlled Multivariate Test).

For more details on experiment types and how variants are assigned, see the [Experiments documentation](https://docs.userpilot.com/in-app-engagement/flows/use-cases/AB-testing).

**Example:**

```json theme={null}
{
  "event_name": "experiment:9:SEEN",
  "attributes": {
    "interaction_id": "experiment_9",
    "is_dismissed": "0",
    "never_show_again": "0",
    "status": "SEEN",
    "total_dismissed": "0",
    "variant": "B"
  }
}
```

***

## Key Data Entities & Relationships

* **Users:** Identified by `user_id`, with `metadata` (traits like `email`, `signup_at`, `plan_type`).
* **Companies:** (B2B) Identified by `company_id`, with properties (e.g., `company_name`, `industry`).
* **Events:** Actions or occurrences, each as a JSON line.
* **Sessions:** Grouped events within a continuous user activity period, identified by `session`.

### Relationships

* A **User** can perform many **Events**.
* Multiple **Events** can occur within a single **Session**.
* A **User** may belong to one **Company**.

***

If you encounter any problems or have questions not covered in this documentation, please reach out to the Userpilot support team through your usual support channels (e.g., in-app chat, email [support@userpilot.com](mailto:support@userpilot.com)).

Provide as much detail as possible about your issue for a faster resolution.