Identify users and track events through HTTP Rest API

Besides Userpilot Javascript SDK for browsers, Userpilot supports identify users and track custom events through Rest API. Identifying users and tracking custom events can help you create powerful user segments to target and track goals as well.

These APIs can be called in any language that supports HTTP requests, you only need to specify your  API_key  and the user/event data that you want to track.

Common use cases

• Historical user identification: customers commonly want to import historical data into Userpilot upon migration or evaluation.
• Server-side event tracking: in certain scenarios there are places for events that are only reachable by your server i.e. email confirmations, or tracking high volume critical events as of marketing campaigns, or sensitive events like user life value which or there is a need to tie the online to the offline behavior of end users.

Authorization

Userpilot API uses API tokens to authenticate requests. You can view your API key in the Environment Page.

Your API key carries many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas.

Authentication to the API is performed via HTTP custom auth token, use  -H 'Authorization: token <your API key here>'  to add your token.

Note: All API requests must be made over HTTPS.

Version

You have to send the api version in Headers. 

-H 'X-API-Version: 2020-09-22'

Identify user API

Calling identify lets you identify users and add metadata about them to track their events, you can call user identify after user's login, signup or when updating their info.

Endpoint

POST {{ANALYTEX_URL}}/v1/identify

Request payload

Example

{
    "user_id": "unique_user_id",
    "metadata": {
        "name": "Username",
   	"email": "user@example.com",
   	"created_at": "1519205055"
	// Additional properties 
    },
    "company": {
       "id": "company_id", // required if company was provided
       "name": "company name",
       "created_at": "1519205055"
	// Additional properties 
    }
}
curl -X POST https://analytex.userpilot.io/v1/identify \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Token API_key' \
  -H 'X-API-Version: 2020-09-22' \
  -d '{"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"}}'

Response

On successful identification, the API will return HTTP code 202

202 Accepted

Identify company API

The Identify Company API allows you to identify and track companies in real-time. This API creates or updates a company profile in Userpilot’s system. It’s designed to capture key company data and provide insights into company engagement and usage patterns.

Endpoint

POST {{ANALYTEX_URL}}/v1/companies/identify

Headers

• Content-Type : application/json
• Authorization : Token <API-KEY>
• X-API-Version : 2020-09-22

Request Payload

Example API Request

curl --location '{{ANALYTEX_URL}}/v1/companies/identify' \\
--header 'Content-Type: application/json' \\
--header 'Authorization: Token <API-KEY>' \\
--header 'X-API-Version: 2020-09-22' \\
--data-raw '{
    "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",
    }
}'

Response

Success (200 OK)

On a successful request, the API will return a 200 OK status with the following JSON response indicating the company has been successfully identified:

{
  "status": "success",
  "message": "Company identified successfully",
  "company_id": "comp123"
}

Error Responses

• Missing company_id (400 Bad Request):

  If the company_id field is missing or invalid, the API will return a 400 Bad Request error with a message explaining the issue:

{
  "status": "error",
  "message": "'company_id' is a required field"
}

• Invalid Authorization (401 Unauthorized):

  If the authorization token is missing or invalid, the API will return a 401 Unauthorized error:

{
  "status": "error",
  "message": "Invalid authorization token"
}

• Rate Limit Exceeded (429 Too Many Requests):

  If you exceed the rate limit for this endpoint, the API will return a 429 Too Many Requests error:

{
  "status": "error",
  "message": "Rate limit exceeded"
}

Important Considerations

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

FAQs

What happens if the company already exists?

If the company_id provided already exists, the API will update the company record with the new metadata provided.

What happens if there is no associated user?

A company without associated users will not appear in the companies dashboard. You must identify at least one user for the company to make it visible.

Calling  track  API will record events about your users with any properties to describe the event. 

Request payload

Example

{
    "user_id": "unique_user_id",
    "event_name": "user_subscribed",
    "metadata": {
        "plan": "free",
   	"created_at": "1519205055"
	// Additional properties 
    }
}
curl -X POST https://analytex.userpilot.io/v1/track \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Token API_key' \
  -H 'X-API-Version: 2020-09-22' \
  -d '{"user_id": "unique_user_id", \
	"event_name": "user_subscribed",
	"metadata": {"plan": "free", "created_at": "1519205055"}}'

Response

On successful event tracking, the API will return HTTP code 202

202 Accepted

Rate limit

Please note that these APIs are limited by 600 requests per minute, you can check the limits on response header. If you exceeded the limit we'll return   429 too many requests  error

x-ratelimit-limit: 600,
x-ratelimit-remaining: 599,
x-ratelimit-reset: 1600854660000