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'

A note about base url

For most customers the API base url is https://analytex.userpilot.io as the examples show.

However, if you are on an enterprise plan which uses a custom endpoint, refer to the Installation page in Settings to retrieve your base url.

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.

Request payload

Field		Type	Description
`user_id`	required	String	ID of the user, must be unique.
`metadata`	optional	Object	Key-value pairs that describes the user. It's useful for storing additional information about the user .
`company`	optional	Object	Key-value pairs that describes the user's company. It's useful for storing additional information about the user's company. Note: if company was provided you must provide `id` in the company object.

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"}}'

Note:

If user’s data has changed you can call identify API to update user's data on Userpilot. It'll check for any new changes on the data and update it. You only need to include whatever has changed (no need to include all user data in each update).

Response

On successful identification, the API will return HTTP code 202

202 Accepted

Track events API

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

Request payload

Field		Type	Description
`user_id`	required	String	ID of the user that this event belongs to.
`event_name`	required	String	The name of the event that should be tracked.
`metadata`	optional	Object	Key-value pairs that describes the tracked event. It's useful for storing additional information about the event.

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