Skip to main content

​
Overview

Userpilot offers a REST API to identify users and track custom events, enabling the creation of detailed user segments and effective goal tracking. This API can be utilized in any programming language that supports HTTP requests by specifying your API_key and the relevant user or event data.

​
Common use cases

  • Historical user identification: Import historical data into Userpilot during migration or evaluation phases.
  • Server-side event tracking: Capture events accessible only via your server, such as email confirmations, high-volume marketing events, or sensitive data like user lifetime value.

​
Authorization

Authenticate API requests using your Userpilot API token, available on the Environment Page. Keep your API key secure and avoid sharing it publicly. Use the following header for authentication: 
-H 'Authorization: token {your API key here}'
Ensure all API requests are made over HTTPS.

​
API Versioning:

Include the API version in your request headers: 
-H 'X-API-Version: 2020-09-22'
HTTP Endpoints: The standard API endpoint is: 
https://analytex.userpilot.io
For Enterprise or EU hosting, refer to the Environment Page for your specific endpoint.

​
Identify User API:

Use the identify endpoint to recognize users and append metadata. Invoke this after user login, signup, or profile updates.
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.
Request Payload:
  • user_id (required): Unique identifier for the user.
  • metadata (optional): Key-value pairs describing the user.
  • company (optional): Key-value pairs describing the user’s company; if provided, an id is mandatory.
Example: 
{
  "user_id": "unique_user_id",
  "metadata": {
    "name": "Username",
    "email": "user@example.com",
    "created_at": "1519205055"
  },
  "company": {
    "id": "company_id",
    "name": "Company Name",
    "created_at": "1519205055"
  }
}
Important Notes:
  • Metadata and Company Values: Only primitive types (string, number, boolean, null) are supported. Arrays or objects as values are not allowed.
  • Data Updates: To update user information, call the identify API with the modified data; only include fields that have changed.
Response: A successful identification returns HTTP status code 202 Accepted.

​
Identify Company API:

Use the identify company endpoint to recognize and track companies in real-time. This API creates or updates a company profile in Userpilot’s system, capturing key company data and providing insights into company engagement and usage patterns. Request Payload:
  • company_id (required): Unique identifier for the company.
  • metadata (optional): Key-value pairs describing the company (e.g., name, industry, plan, monthly_spend, etc.).
Example: 
{
  "company_id": "comp123",
  "metadata": {
    "name": "Acme Corporation",
    "industry": "SaaS",
    "plan": "Enterprise",
    "monthly_spend": 1000,
    "lifecycle_stage": "Customer",
    "location": "San Francisco, CA",
    "signup_date": "2023-01-15T12:34:56Z"
  }
}
Important Notes:
  • Company-User Association: A company will not appear on the companies dashboard unless there is at least one associated user. Ensure that users are identified for the company to ensure visibility in the Userpilot dashboard.
  • Metadata Values: Only primitive types (string, number, boolean, null) are supported. Arrays or objects as values are not allowed.
  • Data Updates: To update company information, call the identify company API with the modified data; only include fields that have changed.
  • inserted_at is auto-handled: The inserted_at field is managed by the API automatically. Any value passed for inserted_at from the caller will be ignored, and the API will use the current date and time as the inserted_at value.
Response: A successful identification returns HTTP status code 200 OK and a response like: 
{
  "status": "success",
  "message": "Company identified successfully",
  "company_id": "comp123"
}
Error Responses:
  • Missing company_id (400 Bad Request):
{
  "status": "error",
  "message": "'company_id' is a required field"
}
  • Invalid Authorization (401 Unauthorized):
{
  "status": "error",
  "message": "Invalid authorization token"
}
  • Rate Limit Exceeded (429 Too Many Requests):
{
  "status": "error",
  "message": "Rate limit exceeded"
}

​
Track Events API:

The track endpoint records events associated with users, allowing you to monitor specific actions. Request Payload:
  • user_id (required): Identifier of the user associated with the event.
  • event_name (required): Name of the event to track.
  • metadata (optional): Key-value pairs providing additional event details.
Example: 
{
  "user_id": "unique_user_id",
  "event_name": "user_subscribed",
  "metadata": {
    "plan": "free",
    "created_at": "1519205055"
  }
}