> ## 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

> Complete reference for Userpilot's data model including User, Company, and Event schemas with field types, identity rules, and relationships.

# 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:

```javascript theme={null}
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

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

```javascript theme={null}
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()`:

```javascript theme={null}
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