Back to top

Taplytics API Reference

Introduction

The Taplytics API is a REST based endpoint for remotely accessing data from Taplytics. Note: API access is only available to users on an Enterprise plan.

API Endpoint

The API endpoint is available at https://api.taplytics.com.

Authentication

All access to the Taplytics API is done using token based authentication. Multiple API keys can be used at the same time, and they can be managed via your account.

Also, note that all requests must be made via https. Any requests over http will be denied.

Authentication is done through your project’s REST API Key. This can be found on the left sidebar under ‘Settings’ for your project. Every request you send through the API must contain this key. It can either be sent as a query parameter called api_token. Example:

https://api.taplytics.com?api_token=e3dddfb4068e-414a-92f1-390ha54603ff

Or, it can be sent in the body of a POST request, if that happens to be what you’re sending to the API:

{ “api_token”: “3dddfb4068e-414a-92f1-390ha54603ff” }

Or, lastly, it can be sent as an HTTP header called x-access-token.

HTTP Responses & Errors

Taplytics uses standard HTTP status codes to identify whether requests are succesful or have failed.

  • 200 OK - All systems go!

  • 204 No Content - The record was succesfully deleted

  • 400 Bad Request - Something’s missing (probably a parameter)

  • 401 Unauthorized - Invalid API key

  • 402 Request Failed - The parameters in your request were valid, but something failed

  • 404 Not Found - The request item does not exist

  • 50x Server Error - Something else went wrong

Custom Data

Most user updatable objects in Taplytics support custom_data as a parameter. The custom_data object is a key:value store for any custom data that you would like to associate with that object.

For example, if you would like to store a custom user id, you can pass the following type of data in to your user object:

{ “custom_data”: { “my_user_id” : “12345”, “first_name” : “Paul”, “last_name” : “Graham” } }

Pagination

When querying collections of data, such as multiple users, push notifications, etc, the Taplytics API uses pagination to return the data. This is done through specifying a page, the number of the page of data you wish to access, as well as the number of unique records you wish to see per_page.

So, if somebody had 100 users they have to GET, they could query https://taplytics.com/users?page=1&per_page=50 to get the first 50 users and https://taplytics.com/users?page=2&per_page=50 to get the last 50 users they have. All collections in the API are sorted by the default time at which they were created.

To crawls large sets of data, the client will often query the data and then traverse through the next pages of the document automatically to get more data. It is not recommended that you try and guess the constructed URLs for pagination.

Thus, Taplytics provides all paginated responses with a Link header included. This header will provide the first and last page of the document, as well as the previous and next page, if available. So, to query a project that has roughly 400 hundreds on the third page of data with 100 users per page would look like:

https://api.taplytics.com/v2/users?api_token=YOUR_API_TOKEN&page=3&per_page=100

With a Link header:

Link: <https://api.taplytics.com/v2/users?api_token=YOUR_API_TOKEN&page=4&per_page=100>; rel='last', <https://api.taplytics.com/v2/users?api_token=YOUR_API_TOKEN&page=2&per_page=100>; rel='next', <https://api.taplytics.com/v2/users?api_token=YOUR_API_TOKEN&page=1&per_page=100>; rel='first'"

Please note that by default, accounts have a pagination limit of 100 items per page.

Users

The users api is the best way to retrieve data about individual users of your app. Users can be read or deleted using this endpoint.

Attribute Type Description
id string The Taplytics id for this user
created_at timestamp The date and time this user was first seen
user_id string The custom user_id that you defined for this user
email string The email address you have defined for this user
first_name string The first name you have defined for this user
last_name string The last name you have defined for this user
name string The full name you have defined for the user
custom_data object The custom data that you have defined for this user
last_seen_ip string The last seen ip address of this user
location object The last location info for this user
session_count integer The number of sessions this user has been a part of

Users By Token Collection

List all Users By Token
GET/v2/usersByToken{?per_page}{?paginationToken}

Example URI

GET /v2/usersByToken?per_page=100?paginationToken="548223f2c7036020742ff21c"
URI Parameters
HideShow
paginationToken
string (optional) Example: "548223f2c7036020742ff21c"

The page token used for pagination. If omitted, the endpoint returns the first page of users. A request will respond with the pagination token for the next page of users.

per_page
integer (optional) Example: 100

An optional parameter to define the number of results you would like returned.

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "nextPaginationToken": "548223f2c7036020742ff21c",
  "numEntities": 1,
  "users": [
    {
      "id": "548223f2c7036020742ff21c",
      "created_at": "2015-01-06T03:51:57+00:00",
      "user_id": "42",
      "email": "jonathan@taplytics.com",
      "first_name": "Jonathan",
      "last_name": "Norris",
      "name": "Jonathan Taylor Thomas Norris",
      "metadata": {
        "occupation": "Bug Fixer",
        "favourite_color": "Chartreuse",
        "favourite movie": "You Don't Mess With The Zohan"
      },
      "last_seen_ip": "123.123.123.123",
      "location": {
        "city_name": "San Francisco",
        "continent_code": "NA",
        "country_code": "USA",
        "country_name": "United States",
        "latitude": 37.77493,
        "longitude": -122.41942,
        "postal_code": null,
        "region_name": "San Francisco",
        "timezone": "Europe/San Francisco"
      },
      "experiments": [
        {
          "experiment_id": "548223f2c7036020742aa21c",
          "variation": "548223f2c7036020742ff21a"
        }
      ],
      "devices": [
        {}
      ],
      "session_count": 16
    }
  ]
}

User

A single User object with all its details, accessed via either ID, email or your custom user ID. If an email or custom ID is provided in the URL parameters, the ID field can be omitted. Note that custom data can only be reliably kept with no more than one level of nesting. If the user currently has a custom data object and one is posted, the two will be merged.

Retrieve a User
GET/v2/users/{id}

Example URI

GET /v2/users/548223f2c7036020742ff21c
URI Parameters
HideShow
id
string (required) Example: 548223f2c7036020742ff21c

String id of the User to retrieve.

user_id
string (optional) Example: 42

Your custom defined user id.

email
string (optional) Example: jonathan@taplytics.com

Your custom defined user email

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "548223f2c7036020742ff21c",
  "created_at": "2015-01-06T03:51:57+00:00",
  "user_id": "42",
  "email": "jonathan@taplytics.com",
  "first_name": "Jonathan",
  "last_name": "Norris",
  "custom_data": {
    "occupation": "Bug Fixer",
    "favourite_color": "Chartreuse",
    "favourite movie": "You Don't Mess With The Zohan"
  },
  "last_seen_ip": "123.123.123.123",
  "location": {
    "city_name": "San Francisco",
    "continent_code": "NA",
    "country_code": "USA",
    "country_name": "United States",
    "latitude": 37.77493,
    "longitude": -122.41942,
    "postal_code": null,
    "region_name": "San Francisco",
    "timezone": "Europe/San Francisco"
  },
  "session_count": 16,
  "gender": "male"
}

Create or Update a User
POST/v2/users/{id}

Example URI

POST /v2/users/548223f2c7036020742ff21c
URI Parameters
HideShow
id
string (required) Example: 548223f2c7036020742ff21c

String id of the User to retrieve.

user_id
string (optional) Example: 42

Your custom defined user id.

email
string (optional) Example: jonathan@taplytics.com

Your custom defined user email

Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "gender": "male",
  "first_name": "Jonathan",
  "last_name": "Norris",
  "user_id": "42",
  "custom_data": {
    "occupation": "Bug Fixer",
    "favourite movie": "You Don't Mess With The Zohan"
  },
  "email": "jonathan@taplytics.com"
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "548223f2c7036020742ff21c",
  "created_at": "2015-01-06T03:51:57+00:00",
  "user_id": "42",
  "email": "jonathan@taplytics.com",
  "first_name": "Jonathan",
  "last_name": "Norris",
  "custom_data": {
    "occupation": "Bug Fixer",
    "favourite_color": "Chartreuse",
    "favourite movie": "You Don't Mess With The Zohan"
  },
  "last_seen_ip": "123.123.123.123",
  "location": {
    "city_name": "San Francisco",
    "continent_code": "NA",
    "country_code": "USA",
    "country_name": "United States",
    "latitude": 37.77493,
    "longitude": -122.41942,
    "postal_code": null,
    "region_name": "San Francisco",
    "timezone": "Europe/San Francisco"
  },
  "session_count": 16,
  "gender": "male"
}

Remove a User
DELETE/v2/users/{id}

Example URI

DELETE /v2/users/548223f2c7036020742ff21c
URI Parameters
HideShow
id
string (required) Example: 548223f2c7036020742ff21c

String id of the User to retrieve.

user_id
string (optional) Example: 42

Your custom defined user id.

email
string (optional) Example: jonathan@taplytics.com

Your custom defined user email

Response  204
HideShow
Headers
Content-Type: application/json; charset=utf-8

Experiments

The experiments api is the best way to retrieve data about your experiments. Experiments can be read or deleted using this endpoint.

Attribute Type Description
id string The Taplytics id for this experiment
project_id string The id of the project where this experiment was created
variations list A list of the variations contained within this experiment
status string The status of this experiment. Can be draft, active, paused or archived

Experiments Collection

List all Experiments
GET/v2/experiments{?per_page}{&page}

Example URI

GET /v2/experiments?per_page=100&page=1
URI Parameters
HideShow
page
integer (optional) Example: 1

The page number used for pagination

per_page
integer (optional) Example: 100

An optional parameter to define the number of results you would like returned

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
[{
     "id": "5a6a0ca339004c0094fa208z",
     "project_id": "5a68fdea39003c0094fx1d6g",
     "description": "ANYTHING",
     "goal_ids": [
         "5a6a0d2186bfc6201339fbob",
         "5a7def3cccd5d340119c8b3a",
         "5b3bd18bdcf7bb20d893f481"
     ],
     "filters": [
         {
             "comparator": "=",
             "type": "osType",
             "_id": "5a6a0ca339103c0094fa208f",
             "values": [
                 "iPhone OS"
             ]
         }
     ],
     "variations": [
         {
             "name": "Variation 1",
             "distributionPercent": 1,
             "_id": "5a6a0ca339003c0094fa2091",
             "dynamicVariables": [
                 {
                     "name": "ANYTHING",
                     "isActive": false,
                     "createdFrom": "device",
                     "defaultValue": "{\"ANYTHING":1}",
                     "variableType": "JSON",
                     "value": "{\"ANYTHING\":1}",
                     "_id": "5adf436633a6c7000c5e1d51"
                 }
             ],
             "webElements": []
         }
     ],
     "baseline": {
         "distributionPercent": 0,
         "dynamicVariables": [
             {
                 "name": "ANYTHING",
                 "isActive": false,
                 "createdFrom": "device",
                 "defaultValue": "{\"ANYTHING\":1}",
                 "variableType": "JSON",
                 "value": "{\"ANYTHING\":1}",
                 "_id": "5adf436643a6x7000c5e1d52"
             }
         ],
         "name": "Baseline"
     },
     "updated_at": "2018-07-05T16:01:12.535Z",
     "created_at": "2018-01-25T16:58:11.155Z",
     "name": "ANYTHING",
     "status": "active"
 }]

Experiment

A single Experiment object with all its details

Retrieve an Experiment
GET/v2/experiments/{id}

Example URI

GET /v2/experiments/548223f2c7036020742ff21c
URI Parameters
HideShow
id
string (required) Example: 548223f2c7036020742ff21c

String id of the Experiment to retrieve.

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": "548223f2c7036020742ff21c",
  "project_id": "52718670ef1a872530000022",
  "variations": [
    "548223f2c7036020742ff21c",
    "512263f2c79g607s142gf21h"
  ],
  "winning_variation": "548223f2c7036020742ff21c",
  "baseline_variation": "548223f2c7036020742ff21c",
  "goal_ids": [
    "54ac360cc4d37a81567a72e7"
  ],
  "status": "active",
  "description": "Disables the Buy button",
  "min_app_version": "1.0",
  "max_app_version": "1.8.4",
  "filters": {
    "version": "1.2.3",
    "os_version": "4.4.4"
  },
  "created_at": "2015-01-06T03:51:57+00:00",
  "updated_at": "2015-01-06T03:51:57+00:00"
}

Remove an Experiment
DELETE/v2/experiments/{id}

Example URI

DELETE /v2/experiments/548223f2c7036020742ff21c
URI Parameters
HideShow
id
string (required) Example: 548223f2c7036020742ff21c

Taplytics id of the experiment you would like to delete.

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "deleted": true,
  "id": "548223f2c7036020742ff21c"
}

Events

The events api allows you to send custom events directly to the Taplytics backend, where they will be stored and accessible for later use.

Attribute Type Description
id string The Taplytics id for this event
session_id string The id of the session the event was created in
name string Custom name for this event
date string Date the event occurred at
value number Some numeric value set during event creation
metaData object Custom metadata sent with the event

Events Collection

Create New Events
POST/v2/events{?session_id}

Post a list of new events to the server. Must provide a session_id with the request, and each event must have a name. No more than 100 events can be sent in a single request body.

Example URI

POST /v2/events?session_id=548223f2c7036020742ff21c
URI Parameters
HideShow
session_id
string (required) Example: 548223f2c7036020742ff21c

Taplytics id of the current user session you wish to send an event for

Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
[{
    "name": "Purchase",
    "date": "2015-01-06T03:50:57+00:00",
    "value": 42,
    "metaData": {
        "occupation": "Bug Fixer",
        "favourite movie": "You Don't Mess With The Zohan"
    },
}]
Response  200

Push Notifications

Ready to take your push notifications to the next level? Use Taplytics’ integrated push notification service to immediately get in touch with your users at exactly the right time.

In general, push objects consist of five main elements.

Attribute Type Description
notification object required - The actual notification that should be sent to each device.
notification.alert string required Notification message that will be seen by the user. Note: this becomes optional if custom_keys has been set.
notification.time_to_live number optional Seconds for which we will attempt to deliver the notification. Slightly different per platform, please read Google’s and Apple’s documentations on it.
image object optional Image data that specifies this push as a rich image push. Images must be less than 10 mb. Requires iOS 10, Android 4.4 or newer and Taplytics iOS SDK 2.19.0, Android SDK 1.18.0 or newer.
image.url string optional The url pointing to the image that should be used for the image push. Image file extension must be .jpg, .jpeg, or .png
image.tl_cdn boolean optional Specifies whether the provided image should be re-uploaded to the Taplytics CDN for delivery. Set to false to send the push using the original URL.
filters array of objects optional - The audience that the push notification is directed towards. If not specified, push will send to all users.
custom_keys object optional - An object of keys and values that will be included in the notification payload that will be sent to the device.
filter_duplicate_content boolean optional - Automatically prevents multiple API push requests with the same message content from delivering multiple notifications to the same user within a 15 minute window. Defaults to true.
schedule object optional - Contains time object of when the push notification will be sent. If not specified, it will be immediate.
production boolean optional - Determines whether your push notification will go to real users or to a Sandbox. Defaults to false.
is_silent boolean optional - If true, push notifications will be sent as a silent background push. No notification will be presented to users.
badge_count number optional - Allows you to change the badge number via the REST API. Setting it to 0 would remove the badge count altogether.

Audience Selection:

To define the audience for your push notification, you can either brodcast your push notification to all clients, or target specific clients. If you wish to send to all users, do not specify any filters.

Filter Fields:

  • The filters field is an array of objects. These objects have the following fields.
Identifier Type Description
type string The type of field by which you wish to filter, possible options can be found in the next table below
comparator string The operator used to compare the given values and those of your users. Can be "=", "<=", ">=", "!="
values array All the values you wish to match your users by. A user will be part of the filter if ANY of the values specified here match the type using the comparator.
dataKey string If you are filtering on custom user data, this field specifies the key of the custom data that you wish to compare. NOTE: only specify this field if the type is equal to "custom_data"

Filter Types:

In order to target specific subsets of your userbase, you will need to use one of the following targeting identifiers for your type field:

Value Description
“an_version” The Android versions by which you will filter. If no "ios_version" filter specified, it will only send to Android
“ios_version” The iOS versions by which you will filter. If no "android_version" filter specified, it will only send to iOS
“os” The OSes you wish to send to. Only use if you are not already specifying versions for the desired OS. Possible values are "iOS" and "Android"
“id” The IDs of the users that you wish to send to
“email” The emails of the users that you wish to send to
“custom_data” Your custom defined custom data for the user by which you will filter. Only works on top level fields (no nesting). NOTE: if using this type, a dataKey field must also be specified in the filter
“gender” Gender of the users you wish to send to (only works if you have specified this on your users beforehand)
“user_id” Custom user IDs by which you can filter
“age” The age of the users by which you can filter
“app_lang” The language of your user’s app by which you can filter
“country” The country of your users by which you can filter
“device_model” The device models of your users by which you can filter
“push_token” Target a specific device by unique push token
“push_token_sandbox” Target a specific dev device by unique push token
Examples - Filters:

“filters”: [{ “type”: “an_version”, “comparator”: “>=”, “values”: [“5.0.0”] }, { “type”: “ios_version”, “comparator”: “!=”, “values”: [“8.0.1”] }, { “type”: “country”, “comparator”: “=”, “values”: [“Canada”, “US”] }, { “type”: “custom_data”, “comparator”: “>=”, “values”: [16], “dataKey”: “dollars spent” }]

This filter will send the push notification to users who:

  • Have an Android phone with a version greater than or equal to 5.0.0 OR have an iPhone with versions not equal to 8.0.1

  • AND are currently in either Canada OR the US

  • AND have a custom data field dollars spent with a value greater than or equal to 16

With great power comes great responsibility. Though this filter language is powerful, since you have so much control over how the data is manipulated, if used incorrectly there could be unintended consequences:

Examples - BAD Filters, DO NOT DO THIS:

“filters”: [{ “type”: “ios_version”, “comparator”: “!=”, “values”: [“8.0.1”, “8.1.3”] }, { “type”: “app_lang”, “comparator”: “>”, “values”: [“en”] }]

  • Since a user is matched if they fulfill ANY of the values in the array, this will send to every iPhone device. If they are on 8.0.1, then obviously they are NOT on 8.1.3. They will pass the check and thus the message will send to them. To avoid this unintended behaviour, create multiple filters per version

  • Here you are using a ‘greater than’ comparator on a string. This will try and match on numerical ASCII values and will produce unexpected results.

Scheduled Messages:

Push notifications can be sent out immediately, or they can be sent out at a specific time. Additionally, they can be sent out at a standard time to everyone, or they can be sent out based on the audience member’s local time.

Identifier Type Description
time string optional The UTC at which your push notification will be sent to every user. Format is UTC: YYYY-MM-DDTHH:MM:SSZ.
local_time string optional The time in any given audience member’s timezone at which you want to send the notification. Format is UTC, with no timezone included: YYYY-MM-DDTHH:MM:SS.

One of these two strings must be provided. If they both are, local time takes precedence. All times must be in the future.

{ “schedule”: { “time”: “2015-11-05T13:15:30Z”, “local_time”: “2015-11-05T13:15:30” } }

This will get sent at each user’s local time.

Push Notification Collection

The default endpoint to send a single push notification, or a batch of notifications.

List all Push Notifications
GET/v2/push{?per_page}{?page}

Example URI

GET /v2/push?per_page=100?page=1
URI Parameters
HideShow
page
integer (optional) Example: 1

The page number used for pagination

per_page
integer (optional) Example: 100

An optional parameter to define the number of results you would like returned

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "548013f2c703f020242ff21c",
    "filters": [
      {
        "type": "an_version",
        "comparator": ">=",
        "values": [
          "5.0.0"
        ]
      },
      {
        "type": "ios_version",
        "comparator": "!=",
        "values": [
          "8.0.1"
        ]
      },
      {
        "type": "country",
        "comparator": "=",
        "values": [
          "Canada",
          "US"
        ]
      },
      {
        "type": "custom_data",
        "comparator": ">=",
        "values": [
          16
        ],
        "dataKey": "dollars spent"
      }
    ],
    "notification": {
      "alert": "Congratulations, you've won a new VCR!"
    },
    "production": false
  }
]

Send a New Push Notification
POST/v2/push

Example URI

POST /v2/push
Request
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "name": "Test",
  "filters": [
    {
      "type": "an_version",
      "comparator": ">=",
      "values": [
        "5.0.0"
      ]
    },
    {
      "type": "ios_version",
      "comparator": "!=",
      "values": [
        "8.0.1"
      ]
    },
    {
      "type": "country",
      "comparator": "=",
      "values": [
        "Canada",
        "US"
      ]
    },
    {
      "type": "custom_data",
      "comparator": ">=",
      "values": [
        16
      ],
      "dataKey": "dollars spent"
    }
  ],
  "notification": {
    "alert": "Congratulations, you've won a new VCR!"
  },
  "image": {
    "url": "https://images.g2crowd.com/uploads/product/image/social_landscape/social_landscape_1489698170/taplytics.jpg",
    "tl_cdn": true
  },
  "filter_duplicate_content": true,
  "production": false,
  "is_silent": false
}
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
    "id": "548013f2c703f020242ff21c", // ID of the push notification
    "name": "Test",
    "status": "sending",
    "created_at": "2015-06-09T18:08:51.194Z",
    "notification": {
        "alert": "Congratulations, you've won a new VCR!"
    },
    "schedule": {
        "now": true
    },
    "production": false
    "filter_duplicate_content": true,
    "filters": [{
        "type": "an_version",
        "comparator": ">=",
        "values": ["5.0.0"]
    },
    {
        "type": "ios_version",
        "comparator": "!=",
        "values": ["8.0.1"]
    },
    {
        "type": "country",
        "comparator": "=",
        "values": ["Canada", "US"]
    },
    {
        "type": "custom_data",
        "comparator": ">=",
        "values": [16],
        "dataKey": "dollars spent"
    }]
}

Push Notification

The default endpoint to retrieve a single push notification

Retrieve a Push Notification
GET/v2/push/

Example URI

GET /v2/push/
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "548013f2c703f020242ff21c",
  "filters": [
    {
      "type": "an_version",
      "comparator": ">=",
      "values": [
        "5.0.0"
      ]
    },
    {
      "type": "ios_version",
      "comparator": "!=",
      "values": [
        "8.0.1"
      ]
    },
    {
      "type": "country",
      "comparator": "=",
      "values": [
        "Canada",
        "US"
      ]
    },
    {
      "type": "custom_data",
      "comparator": ">=",
      "values": [
        16
      ],
      "dataKey": "dollars spent"
    }
  ],
  "notification": {
    "alert": "Congratulations, you've won a new VCR!"
  },
  "production": false
}

Generated by aglio on 19 Mar 2020