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

# Identify User

> The Identify User API allows you to create or update user profiles in real time, either individually or in bulk. Use this API to keep your user data in sync with Userpilot for analytics, segmentation, and personalized experiences.

## When to Use

Use the HTTP Identify API when:

* Creating users from server-side code (e.g., after signup in your backend)
* Updating user properties without a page load
* Syncing user data from external systems
* Your application doesn't run in a browser (backend services, mobile apps without SDK)

<Warning>
  **PII Data Notice**

  Before 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.
</Warning>

**Use the JavaScript SDK instead** when:

* Users are interacting with your web application in a browser
* You need to display Userpilot content immediately after identification

## Prerequisites

* Userpilot API Key (not App Token) from [Settings > Environment](https://run.userpilot.io/environment)
* Knowledge of your API environment (US or EU)

## Individual Identify

### Endpoint

```http theme={null}
[POST] https://analytex.userpilot.io/v1/identify
```

<Note>
  The endpoint URL uses the `analytex` environment. For EU data residency, use
  `analytex-eu` instead. See [Environment
  Settings](https://run.userpilot.io/environment) for your specific endpoint.
</Note>

{" "}

### Headers

| Header          | Value                  | Required |
| --------------- | ---------------------- | -------- |
| `Content-Type`  | `application/json`     | Yes      |
| `Authorization` | `Token {YOUR_API_KEY}` | Yes      |
| `X-API-Version` | `2020-09-22`           | Yes      |

### Request Body

| Field      | Type   | Required | Description                                                |
| ---------- | ------ | -------- | ---------------------------------------------------------- |
| `user_id`  | string | Yes      | Unique identifier for the user                             |
| `metadata` | object | No       | Key-value pairs describing the user                        |
| `company`  | object | No       | Object with at least an `id` field for company association |

### Example

```json theme={null}
{
  "user_id": "user_001",
  "metadata": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "company": {
    "id": "company_001"
  }
}
```

### Response

A successful identification returns HTTP status code 202 Accepted.

<Warning>
  The `user_id` field is required. If you include a `company` object, it must
  have at least an `id` field.
</Warning>

***

## Bulk Operations

For bulk user identification and updates, see the dedicated documentation:

* **[Bulk Identify Users](../bulk-updates/users)** - For bulk user operations

These articles provide comprehensive details on endpoints, authentication, request/response examples, limitations, best practices, and troubleshooting for large-scale data synchronization.

***

## Common Issues

| Error              | Cause                | Solution                                                 |
| ------------------ | -------------------- | -------------------------------------------------------- |
| 401 Unauthorized   | Invalid API key      | Verify API key (not App Token) from Environment settings |
| 400 Bad Request    | Missing `user_id`    | Include `user_id` field in request body                  |
| 400 Bad Request    | Company without `id` | If `company` object included, it must have `id` field    |
| User not appearing | Wrong environment    | Verify endpoint matches your environment (US vs EU)      |

## Related

* [Track Event API](/api-references/real-time/track-event) - Track user actions
* [Identify Company API](/api-references/real-time/identify-company) - Create/update companies
* [Bulk Identify Users](/api-references/bulk-updates/users) - High-volume user operations
* [Data Model Reference](/reference/data-model) - User and company schema details
* [JavaScript SDK identify()](/developer/installation/web) - Browser-based identification