Skip to main content
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.
FieldTypeRequiredDescription
event_typeStringYesMust be identify_user
user_idStringYesUnique identifier for the user.
metadataObjectYesKey-value pairs of user attributes.
sourceStringYesIndicates the origin of the event data.
inserted_atString (ISO)YesTimestamp 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": "john.doe@example.com",
    "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.
FieldTypeRequiredDescription
event_typeStringYesMust be identify_company
company_idStringYesUnique identifier for the company.
sourceStringYesIndicates the origin of the event data.
metadataObjectYesKey-value pairs of company attributes.
inserted_atString (ISO)YesTimestamp 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.
FieldTypeRequiredDescription
event_typeStringYesMust be page_view
user_idStringYesUnique identifier for the user
hostnameStringYesHostname of the page (e.g., example.com)
pathnameStringYesPathname of the page (e.g., /dashboard)
sourceStringYesIndicates the origin of the event data
inserted_atString (ISO)YesTimestamp 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.
FieldTypeRequiredDescription
event_typeStringYesMust be track
user_idStringYesUnique identifier for the user.
event_nameStringYesName of the event (e.g., button_click).
sourceStringYesIndicates the origin of the event data.
metadataObjectNoKey-value pairs of event-specific attributes
inserted_atString (ISO)YesTimestamp 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"
  }
}