Skip to main content

​
Userpilot Data Model

This reference describes the core data entities in Userpilot and how they relate to each other.

​
Entity Relationships

Company (1) ──────< User (many)
   │                   │
   │                   │
   └───< Company       └───< User
         Properties          Properties
                              │
                              │
                        Event (many)
                              │
                              └───< Event
                                    Properties

​
User

A User represents an individual who interacts with your application.

​
Required Fields

FieldTypeDescription
user_idstringUnique identifier for the user. Must be stable across sessions.

​
Reserved Fields

These fields have special meaning in Userpilot:
FieldTypeDescription
namestringUser’s display name
emailstringUser’s email address
created_atISO8601 dateWhen the user account was created
signed_up_atISO8601 dateAlias for created_at
first_seen_atISO8601 dateAuto-set by Userpilot on first identify
last_seen_atISO8601 dateAuto-updated by Userpilot on each identify

​
Custom Properties

Any additional fields passed to identify() become custom user properties: 
userpilot.identify("user_123", {
  name: "Jane Doe",
  email: "[email protected]",
  plan: "enterprise",           // custom string
  mrr: 500,                     // custom number
  trial_ends: "2025-02-01",     // custom date (ISO8601)
  is_admin: true                // custom boolean
});

​
Identity Rules

  • user_id must be unique per environment
  • user_id should be stable (don’t use session IDs or random values)
  • Calling identify() with the same user_id updates the existing user
  • Properties are merged, not replaced (existing properties persist unless overwritten)
  • To remove a property, set it to null

​
Company

A Company represents an organization that groups multiple users.

​
Required Fields

FieldTypeDescription
idstringUnique identifier for the company

​
Reserved Fields

FieldTypeDescription
namestringCompany display name
created_atISO8601 dateWhen the company was created

​
Custom Properties

userpilot.identify("user_123", {
  company: {
    id: "company_456",
    name: "Acme Inc",
    plan: "growth",              // custom string
    employee_count: 50,          // custom number
    signed_contract: "2024-01-15" // custom date
  }
});

​
Identity Rules

  • Company id must be unique per environment
  • Users are associated with a company via the company object in identify()
  • A user can only belong to one company at a time
  • Changing the company id in identify() moves the user to the new company
  • Company properties are merged, not replaced

​
Event

An Event represents a user action or occurrence.

​
Tracked Events

Sent via userpilot.track(): 
userpilot.track("completed_onboarding", {
  steps_completed: 5,
  time_spent: 120
});
FieldTypeDescription
event_namestringName of the event (required)
metadataobjectOptional key-value pairs

​
Auto-captured Events

Automatically recorded (if enabled):
Event TypeDescription
$pageviewPage/URL visited
$clickElement clicked
$changeInput field changed
$submitForm submitted

​
Event Properties

Events automatically include:
FieldTypeDescription
user_idstringUser who triggered the event
company_idstringUser’s company (if set)
timestampISO8601When the event occurred
page_urlstringURL where event occurred
session_idstringBrowser session identifier

​
Data Types

TypeFormatExample
stringUTF-8 text"enterprise"
numberInteger or float500, 99.99
booleantrue or falsetrue
dateISO8601"2025-01-15", "2025-01-15T10:30:00Z"
arrayNot supportedUse comma-separated strings instead

​
Data Limits

LimitValue
Property name length255 characters
Property value length65,535 characters
Properties per user500
Properties per company500
Event metadata size10 KB
Events per API call1 (individual) or 1000 (bulk)

​
Environment Separation

  • Production and staging environments are completely separate
  • Users, companies, and events do not cross environments
  • Each environment has its own App Token and API Key
  • Content created in staging does not appear in production