​

Userpilot Data Model

​

Entity Relationships

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

​

User

​

Required Fields

​

Reserved Fields

​

Custom Properties

userpilot.identify("user_123", {
  name: "Jane Doe",
  email: "jane@example.com",
  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

​

Required Fields

​

Reserved Fields

​

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

​

Tracked Events

userpilot.track("completed_onboarding", {
  steps_completed: 5,
  time_spent: 120
});

​

Auto-captured Events

​

Event Properties

​

Data Types

​

Data Limits

​

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