Event Schema

Detailed schema for events supported by the Import API.

This page documents the event types and required fields for importing data into Userpilot using the Import API. Each record in your import file must conform to one of the following event schemas. Supported event types are identify_user, identify_company, page_view, and track.

---

1. Identify User

Identifies or updates the attributes of a user.

Field	Type	Required	Description
event_type	String	Yes	Must be identify_user
user_id	String	Yes	Unique identifier for the user.
metadata	Object	Yes	Key-value pairs of user attributes.
source	String	Yes	Indicates the origin of the event data.
inserted_at	String (ISO)	Yes	Timestamp of when the data was recorded.

Example Payload:

{
  "event_type": "identify_user",
  "event_name": "",
  "source": "web-client",
  "user_id": "user_id",
  "company_id": "company_id",
  "hostname": "example.com",
  "pathname": "/users/list",
  "country_code": "UK",
  "screen_width": 859,
  "screen_height": 746,
  "operating_system": "Mac",
  "browser": "Chrome",
  "browser_language": "en-US",
  "user_agent": "Chrome - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36",
  "device_type": "Desktop",
  "inserted_at": "2024-07-28 08:55:35.874555",
  "metadata": {
    "name": "John Doe",
    "email": "[e-mail]",
    "job_title": "Solution Architect",
    "department": "Engineering",
    "squad": "CORE Squad",
    "branch_location": "Dublin, Ireland",
    "sign_up_date": "2023-11-01 14:35:36.173103",
    "total_logins": 28,
    "days_since_last_login": 7
  }
}

---

2. Identify Company

Identifies or updates the attributes of a company.

Field	Type	Required	Description
event_type	String	Yes	Must be identify_company
company_id	String	Yes	Unique identifier for the company.
source	String	Yes	Indicates the origin of the event data.
metadata	Object	Yes	Key-value pairs of company attributes.
inserted_at	String (ISO)	Yes	Timestamp of when the data was recorded.

Example Payload:

{
  "event_type": "identify_company",
  "source": "web-client",
  "company_id": "company_id",
  "inserted_at": "2024-07-28 08:55:35.874555",
  "metadata": {
    "name": "Acme Labs Inc.",
    "industry": "Software Solutions",
    "branches_count": 3,
    "Headquarter": "Dublin, Ireland"
  }
}

---

3. Page View

Logs a page view by a user.

Field	Type	Required	Description
event_type	String	Yes	Must be page_view
user_id	String	Yes	Unique identifier for the user
hostname	String	Yes	Hostname of the page (e.g., example.com)
pathname	String	Yes	Pathname of the page (e.g., /dashboard)
source	String	Yes	Indicates the origin of the event data
inserted_at	String (ISO)	Yes	Timestamp of when the page view occurred

Example Payload:

{
  "event_type": "page_view",
  "event_name": "",
  "source": "web-client",
  "user_id": "user_id_10",
  "company_id": "company_id_60",
  "hostname": "example.com",
  "pathname": "/dashboard/",
  "country_code": "US",
  "screen_width": 859,
  "screen_height": 746,
  "operating_system": "",
  "browser": "",
  "browser_language": "en-US",
  "user_agent": "Chrome - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36",
  "device_type": "Desktop",
  "inserted_at": "2024-07-28 08:55:34.229738"
}

---

4. Track Event

Tracks a custom user action or event.

Field	Type	Required	Description
event_type	String	Yes	Must be track
user_id	String	Yes	Unique identifier for the user.
event_name	String	Yes	Name of the event (e.g., button_click).
source	String	Yes	Indicates the origin of the event data.
metadata	Object	No	Key-value pairs of event-specific attributes
inserted_at	String (ISO)	Yes	Timestamp of when the event occurred.

Example Payload:

{
  "event_type": "track",
  "event_name": "account_upgraded",
  "source": "web-client",
  "user_id": "user_id_123",
  "company_id": "",
  "hostname": "example.com",
  "pathname": "/subscription/plans",
  "country_code": "UK",
  "screen_width": 859,
  "screen_height": 746,
  "operating_system": "Mac",
  "browser": "Chrome",
  "browser_language": "en-US",
  "user_agent": "Chrome - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36",
  "device_type": "Desktop",
  "inserted_at": "2024-12-01T08:55:43.220396",
  "metadata": {
    "old_plan": "Basic",
    "new_plan": "Premium",
    "upgrade_date": "2024-12-01T08:55:43.220396"
  }
}