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.
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
| Field | Type | Description |
|---|
user_id | string | Unique identifier for the user. Must be stable across sessions. |
Reserved Fields
These fields have special meaning in Userpilot:
| Field | Type | Description |
|---|
name | string | User’s display name |
email | string | User’s email address |
created_at | ISO8601 date | When the user account was created |
signed_up_at | ISO8601 date | Alias for created_at |
first_seen_at | ISO8601 date | Auto-set by Userpilot on first identify |
last_seen_at | ISO8601 date | Auto-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: "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 environmentuser_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
| Field | Type | Description |
|---|
id | string | Unique identifier for the company |
Reserved Fields
| Field | Type | Description |
|---|
name | string | Company display name |
created_at | ISO8601 date | When 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
});
| Field | Type | Description |
|---|
event_name | string | Name of the event (required) |
metadata | object | Optional key-value pairs |
Auto-captured Events
Automatically recorded (if enabled):
| Event Type | Description |
|---|
$pageview | Page/URL visited |
$click | Element clicked |
$change | Input field changed |
$submit | Form submitted |
Event Properties
Events automatically include:
| Field | Type | Description |
|---|
user_id | string | User who triggered the event |
company_id | string | User’s company (if set) |
timestamp | ISO8601 | When the event occurred |
page_url | string | URL where event occurred |
session_id | string | Browser session identifier |
Data Types
| Type | Format | Example |
|---|
| string | UTF-8 text | "enterprise" |
| number | Integer or float | 500, 99.99 |
| boolean | true or false | true |
| date | ISO8601 | "2025-01-15", "2025-01-15T10:30:00Z" |
| array | Not supported | Use comma-separated strings instead |
Data Limits
| Limit | Value |
|---|
| Property name length | 255 characters |
| Property value length | 65,535 characters |
| Properties per user | 500 |
| Properties per company | 500 |
| Event metadata size | 10 KB |
| Events per API call | 1 (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
