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.

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

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

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