Identify User

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)

PII Data NoticeBefore 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.

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
Knowledge of your API environment (US or EU)

Individual Identify

Endpoint

[POST] https://analytex.userpilot.io/v1/identify

The endpoint URL uses the analytex environment. For EU data residency, use analytex-eu instead. See Environment Settings for your specific endpoint.

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

{
  "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.

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

Bulk Operations

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

Bulk Identify 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)

Track Event API - Track user actions
Identify Company API - Create/update companies
Bulk Identify Users - High-volume user operations
Data Model Reference - User and company schema details
JavaScript SDK identify() - Browser-based identification

For any questions or concerns please reach out to support@userpilot.com

APIs

Real-time HTTP

Bulk Identify/Update

Bulk Import

Bulk Export

Bulk Delete

When to Use

Prerequisites

Individual Identify

Endpoint

Headers

Request Body

Example

Response

Bulk Operations

Common Issues

​When to Use

​Prerequisites

​Individual Identify

​Endpoint

​Headers

​Request Body

​Example

​Response

​Bulk Operations

​Common Issues

​Related

When to Use

Prerequisites

Individual Identify

Endpoint

Headers

Request Body

Example

Response

Bulk Operations

Common Issues

Related