trigger.ly REST API

Users and Events

We track two different types of objects, "users" and "events". Events are usually performed by users.

Users can have arbitary attributes, but there a couple of special ones.

id (required) - A unique user id, this can also be an email address.
email (required for sending emails) : The user's email address.

Just like users, events can have arbitary attributes. The following are special event attributes:

type (required) - The type of the event, for example a "login" or a "purchase".
user_id (optional) - The id of the user that has performed the event.
date (optional) - The date when the event was performed. See the section on date formatting below. By default we use the date of the API call.

Authentication

For all API calls outlined below, you must pass your API Token as an api_token parameter. You can find your API token on the account profile page.

Data Encoding

All data must be in JSON format. However, instead of passing raw JSON, the data must be encoded in Base64 and passed as a data parameter. This makes it easy to pass complex objects using HTTP query parameters without needing to worry about the character encoding.

Most languages have built-in libraries to encode data in Base64. For example in Ruby:

require 'base64'
data = '{"id": "user13@gmail.com", "email": "user13@gmail.com", "name": "Jeff Dean"}'
encoded = Base64.encode64(data) #eyJpZCI6ICJ1c2VyMTNAZ21haWwuY29tIiwgImVtYWlsIjogInVzZXIxM0BnbWFpbC5jb20iLCAibmFtZSI6ICJKZWZmIERlYW4ifQ
original_data = Base64.decode64(encoded) #'{"id": "user13@gmail.com", "email": "user13@gmail.com", "name": "Jeff Dean"}'

Note that you must still URL-encode your API request, even with Base64 data.

Data Types & Date Formats

We automatically recognize String, Number and Boolean datatypes based on the JSON values you send us. You may manually "overwrite" the data types in the user interface.

Unfortunately JSON does not have a native date format. If you do send us dates, please make sure you send them in one of the following formats as Strings. Most programming languages should have built-in function to format dates appropriately.

Wed, 04 Jul 2001 12:08:56 -0700       (EEE, dd MMM yyyy HH:mm:ss Z) (RFC 2822)
2001-07-04T12:08:56.235-0700          (yyyy-MM-dd'T'HH:mm:ss.SSSZ) (ISO 8601)
2001-07-04                            (yyyy-MM-dd)
2011/07/04                            (yyyy/MM/dd)

Tracking Users `GET http://api.trigger.ly/v1/users/track`

Creates a new user or updates a current user with a given id.

Example:

GET http://api.trigger.ly/v1/users/track?api_token=fae3009c1123ab827aa5e0929d2d0d8b&data=eyJpZCI6ICJ1c2VyMTNAZ21haWwuY29tIiwgImVtYWlsIjogInVzZXIxM0BnbWFpbC5jb20iLCAibmFtZSI6ICJKZWZmIERlYW4iLCAiYWdlIjogMzEsICJnZW5kZXIiOiAibWFsZSIsICJzaWdudXBfZGF0ZSI6ICIyMDEyLTEyLTI0In0=&image=1

Before Base64 encoding, the data corresponded to

{"id": "user13@gmail.com", "email": "user13@gmail.com", "name": "Jeff Dean", "age": 31, "gender": "male", "signup_date": "2012-12-24"}

URL Parameters

api_token (required) - For authentication.
data (required) - The user JSON object in Base64 encoding.
image (optional) - If set to 1, we return a 1x1 pixel image. This can be used to easily embed calls into websites or emails.

Tracking Events `GET http://api.trigger.ly/v1/events/track`

Creates a new event.