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  write_token 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 write key in the application settings here.

Your API write 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 write key here>' to add your write 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://api.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://api.userpilot.io/v1/identify \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Token write_token' \
  -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://api.userpilot.io/v1/track \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Token write_token' \
  -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
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.