Event Schema

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.
When a flow is part of an experiment, both experiment:* and experience:* events are generated to track experiment participation and flow interaction respectively.

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:

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

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

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

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

{
  "event_name": "experience:493:DISMISSED",
  "attributes": {
    "interaction_id": "experience_493",
    "is_dismissed": "1",
    "status": "DISMISSED",
    "total_dismissed": "1"
  }
}

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

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. Example:

{
  "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). Provide as much detail as possible about your issue for a faster resolution.

APIs

Real-time HTTP

Bulk Identify/Update

Bulk Import

Bulk Export

Bulk Delete

Event Structure

Internal Event ID

Event Name & Type

Source

Attributes Schema

Interaction Attributes

Surveys (`survey_module` events)

Checklists (`checklist` and `checklist_task` events)

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

NPS Events

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

Experiments (`experiment` events)

Key Data Entities & Relationships

Relationships

​Event Structure

​Internal Event ID

​Event Name & Type

​Source

​Attributes Schema

​Interaction Attributes

​Surveys (survey_module events)

​Checklists (checklist and checklist_task events)

​Resource Center and Articles (resource_center, resource_center_article events)

​NPS Events

​Flow and Flow Steps (experience, experience_step events)

​Experiments (experiment events)

​Key Data Entities & Relationships

​Relationships

Event Structure

Internal Event ID

Event Name & Type

Source

Attributes Schema

Interaction Attributes

Surveys (`survey_module` events)

Checklists (`checklist` and `checklist_task` events)

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

NPS Events

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

Experiments (`experiment` events)

Key Data Entities & Relationships

Relationships