Skip to main content

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.

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.
PII Data NoticeBefore passing any Personally Identifiable Information (PII) such as names, emails, or other sensitive user data to Userpilot:
  • Security & Compliance: Verify internally with your legal, security, and compliance teams that doing so aligns with your organization’s data privacy policies and applicable regulations (e.g., GDPR, CCPA).
  • Data Type Mapping: Ensure correct data type mapping for all properties. Userpilot supports String, Numeric, and Date types. Make sure dates are in ISO8601 format and numeric values are properly formatted. Incorrect type mapping can cause issues with segmentation, analytics, and debugging.
  • Debugging: Proper data formatting is crucial for effective debugging and troubleshooting. Verify that your data maps correctly to Userpilot’s expected formats before implementation.

​
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"
  }
}