Skip to main content

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.

​
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

​
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

HeaderValueRequired
Content-Typeapplication/jsonYes
AuthorizationToken {YOUR_API_KEY}Yes
X-API-Version2020-09-22Yes

​
Request Body

FieldTypeRequiredDescription
user_idstringYesUnique identifier for the user
metadataobjectNoKey-value pairs describing the user
companyobjectNoObject 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: These articles provide comprehensive details on endpoints, authentication, request/response examples, limitations, best practices, and troubleshooting for large-scale data synchronization.

​
Common Issues

ErrorCauseSolution
401 UnauthorizedInvalid API keyVerify API key (not App Token) from Environment settings
400 Bad RequestMissing user_idInclude user_id field in request body
400 Bad RequestCompany without idIf company object included, it must have id field
User not appearingWrong environmentVerify endpoint matches your environment (US vs EU)