Permutive Developer Hub

Welcome to the Permutive developer hub. You'll find comprehensive guides and documentation to help you start working with Permutive as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started
Suggest Edits

Introduction to Permutive

 

Permutive is the world's fastest data platform. Traditional DMPs take hours to update segments and targeting. Permutive does it in milliseconds. You can access our platform via our Dashboard and integrations, as well as our API.

This documentation details the Permutive platform, and how it can be used via our API.

Suggest Edits

Who is this documentation for?

 

If you're a marketer, the Permutive dashboard is the best place for you to interact with our product. We've got a help centre where you can get support on using it here.

If you're a developer, this documentation is for you. We detail how to use the Permutive product via API or one of our SDKs.

Support Documentation

For information on using the Permutive product and dashboard, outside of the API, please see our Support Documentation.

Suggest Edits

Getting in Touch

 

If you need help with this API, or Permutive generally, get in touch using the Intercom chat widget on this page or by emailing support@permutive.com

Suggest Edits

Authentication

 

In order to make requests to the Permutive API, you must provide a project API key via the X-API-KEY header. Permutive supports two types of keys for projects: public and private keys.

Mode
Protocol
Description

Public API key

HTTP, HTTPS

When: Should be used when you can't guarantee the key won't be seen by others (e.g. on your site or in an app).

Why: Can create and retrieve events for users.

Private API key

HTTPS

When: Should only be used when you can guarantee the key won't be seen by others (e.g. on a private server).

Why: Supports all public key permissions

Managing API keys

You can create and delete API keys from your project settings page.

Suggest Edits

Versioning

 

All API requests require specifying the API version to ensure your call is using the correct version. The version of the API is specified in the URL at the leftmost (highest) scope of the path:

http(s)://api.permutive.com/{version}/...

Version numbers are simple ordinals, v1, v2, and so forth.

The current version of the Permutive API is v1.1.

Fixes, improvements, and additions for a given version of the API are made in a backwards-compatible manner to ensure each version has a stable interface across its lifetime. While we don’t expect public endpoints to change greatly, keep in mind that the API is continuously under development.

Suggest Edits

Requests & Responses

 

The Permutive API follows RESTful principles. It is designed to have predictable, resource-oriented URLs and make use of built-in HTTP features such as HTTP response codes and HTTP authentication.

Every bit of data exchanged between clients and the API is JSON, including errors, so all API requests should set the Content-Type header to application/json.

Field types

IDs and referencing

All resource and anonymous user IDs are represented in UUID format.

Timestamps

All timestamps are requested and returned in ISO8601 format.

Permutive uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the information provided in the request (e.g. a required parameter was missing), and codes in the 5xx range indicate an error with Permutive's servers.

HTTP Status Codes

You may encounter the following response codes. Any unsuccessful response will contain more information to help you identify the cause of the problem.

200
OK

Everything worked as expected and the request succeeded.

400
Bad Request

The request could not be understood by the server, usually due to malformed syntax such as a missing required parameter.

401
Unauthorized

The client has not provided a valid Authentication HTTP header.

403
Forbidden

The client has provided a valid Authentication header, but it does not have permission to access this resource.

404
Not Found

The requested resource cannot be found or does not exist.

500, 502, 503, 504
Internal Server Error

The server encountered an error while processing your request and failed. Something went wrong on Permutive's end.

Subcodes

If there has been an error (non-200 response), the body of the response will be a JSON object that describes the error in more detail.

To help you better understand what went wrong and reference the problem, the API defines an error subcode and human-readable messages for every type of error that can occur. The docs field provides a resource where you can find out more information about this error. If you wish to contact our support team about any API errors, you can reference the request_id of your request.

All error responses from the API follow a common format. Here's an example response to a request with an invalid API key:

HTTP/1.1 401 Unauthorized
{
  "request_id": "e2cef6f6-296d-4044-b362-73fb2bce4a72",
  "error": {
    "status": "Unauthorized",
    "code": 2000,
    "message": "The API key provided is invalid.",
    "cause": "This key does not exist.",
    "docs": "https://developer.permutive.com/docs/errors/401/2000"
  }
}

Every field is guaranteed, other than cause which is optional.

Understanding Errors

If you're unclear on what an error means, or want more help please get in touch using the chat widget or by emailing support@permutive.com

To check the status of the API, head over to our status page. Here you can subscribe to updates so that you'll be notified of any issues and planned maintenance.

The status page also contains an archive of past downtime and API issues for your reference.

Suggest Edits

Introduction to Events

 

Events are at the core of Permutive. We collect events on user behaviours, which are then used to determine segments users fall into.

What are events?

An event is an action someone takes on your site or app. You can define as many events as you wish.

Examples of Events

Clicking a 'buy now' button on a product page.
Playing a video on a news article.

What are properties?

Every event you send to Permutive has properties associated with it. Properties are additional information associated with the event. When you send events to Permutive, you can include any properties you want.

Examples of Properties

Event: Add item to cart

Properties:

  • product: ‘widget’
  • price: ‘4.99’
  • $item_id: '12345'

In order to prevent malformed events being sent into Permutive, event schemas are enforced. Permutive will infer an event schema the first time an event is received. If you'd like to migrate a schema, please email changes to support@permutive.com.

User IDs

Every event in Permutive is tied to a user.

When you send an event to Permutive, you need to include a user_id, which is the ID of the user the event belongs to.

User IDs are used to record events against the user that performed them, and sessions are used to cluster events which occur within a concentrated period of time.

For more information about users, read Introduction to Users.

User IDs in SDKs

If you’re using a Permutive SDK, user_id’s are generated, stored and included in the event tracking method by default. If you’d like to set your own, please refer to the SDK documentation on GitHub.

Suggest Edits

Track an Event

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.permutive.com/v1.1/events
curl --request POST \
  --url https://api.permutive.com/v1.1/events
var request = require("request");

var options = { method: 'POST', url: 'https://api.permutive.com/v1.1/events' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.permutive.com/v1.1/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.permutive.com/v1.1/events");

xhr.send(data);
import requests

url = "https://api.permutive.com/v1.1/events"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

user_id
string
required

The ID of the user that the event belongs to

name
string
required

An identifier for the event, e.g. EmailSubscription. Must only contain characters in [a-zA-Z0-9_].

properties
object

An object containing the properties to associate with this event. Property keys must only contain characters in [a-z0-9_].

 
 

Event schemas

It's important to note that Permutive enforces event schemas to ensure data consistency and validity.

If an event doesn't match the expected schema, it will be rejected and a 400 error returned. Event schemas are viewable in the dashboard. Where Permutive hasn't received an event type before, it will infer the event's schema.

To migrate an event schema, please email support.

Time Attribute

When streaming in data in real-time (e.g. from within an app), Permutive sets a time attribute for events to the current time in UTC.

Request

curl https://api.permutive.com/v1.1/events \
	-H 'X-API-Key: f9975143-2d88-46dc-9247-1fb6c790e1cc' \
  -H 'Content-Type: application/json' \
  -d '{
        "user_id": "8cc26071-25a7-4033-b2c6-ff0fcb5e04a3",
        "name": "EmailSubscription",
        "properties": {
          "email": "mark@facebook.com",
          "subscriptions": {
            "newsletter": true,
            "updates": false
          }
        }
      }'

Response

HTTP/1.1 200 OK
{
  "id": "f45992d8-dc4b-4b47-9705-133ae0031486",
  "user_id": "8cc26071-25a7-4033-b2c6-ff0fcb5e04a3",
  "name": "EmailSubscription",
  "time": "2015-01-26T13:55:17.112Z",
  "properties": {
    "email": "mark@facebook.com",
    "subscriptions": {
      "newsletter": true,
      "updates": false
    }
  }
}
HTTP/1.1 400 Bad Request
{
  "request_id": "147c6bb5-9492-4964-a809-82417d1ef363",
  "error": {
    "docs": "https://developer.permutive.com/docs/errors/400/1007",
    "code": 1007,
    "status": "Bad Request",
    "cause": "The event's properties do not conform to the configured schema.",
    "message": "A validation check carried out by the server did not succeed."
  }
}
Suggest Edits

Viewing Events

 

When events have been sent to Permutive, they will show up in your dashboard. Here you can view an event's properties, get a count of the number of events of a given type, and inspect recently received events.

Screenshot of Events view in Permutive Dashboard

Screenshot of Events view in Permutive Dashboard

Events can also be accessed via the API and SDKs, this is covered in more detail in the next section.

Suggest Edits

Get a User's Events

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.permutive.com/v1.1/events
curl https://api.permutive.com/v1.1/events?user_id=2ff3c50a-ecdb-47a8-a3b7-35da24a26f20 \
	-H 'X-API-Key: f9975143-2d88-46dc-9247-1fb6c790e1cc' \
  -H 'Content-Type: application/json'
curl https://api.permutive.com/v1/events?user_id=2ff3c50a-ecdb-47a8-a3b7-35da24a26f20?from=2015-01-26T00:00:00Z&to=2015-01-27T00:00:00Z \
	-H 'X-API-Key: f9975143-2d88-46dc-9247-1fb6c790e1cc' \
  -H 'Content-Type: application/json'
A binary file was returned

You couldn't be authenticated

HTTP/1.1 200 OK
[
  {
    "id": "1b0a37f9-bb82-43f8-8a50-bc5985e311b9",
    "user_id": "2ff3c50a-ecdb-47a8-a3b7-35da24a26f20",
    "name": "ArticlePageview",
    "time": "2016-01-26T13:33:37.006Z",
    "properties": {
      "engaged_time": 65,
      "completion": 0.85888045,
      "url": "http://trantordaily.com/article/1-elon-musk",
      "$document": {
        "id": "50991",
        "collection": "documents",
        "properties": {
          "category": "business",
          "tags": ["business", "finance", "economics"]
        },
        "time": "2016-01-20T13:33:37.006Z"
      }
    }
  },
  {
    "id": "35b92828-8c25-430f-8ed0-dbcf83dc5033",
    "user_id": "2ff3c50a-ecdb-47a8-a3b7-35da24a26f20",
    "name": "EmailSubscription",
    "time": "2015-01-26T13:55:17.112Z",
    "properties": {
      "email": "mark@facebook.com",
      "subscriptions": {
        "newsletter": true,
        "updates": false
      }
    }
  },
  {
    "id": "88b96f62-d7f2-4beb-828b-cdff6d2a335a",
    "user_id": "2ff3c50a-ecdb-47a8-a3b7-35da24a26f20",
    "name": "ArticlePageview",
    "time": "2016-01-26T13:41:12.004Z",
    "properties": {
      "engaged_time": 15,
      "completion": 0.46012,
      "url": "http://trantordaily.com/article/2-forget-warp-drive",
      "$document": {
        "id": "39881",
        "collection": "documents",
        "properties": {
          "category": "technology",
          "tags": ["technology", "science", "economics"]
        },
        "time": "2016-01-28T22:33:37.006Z"
      }
    }
  }
]
HTTP/1.1 400 Bad Request
{
  "status": "ResourceNotFound",
  "code": 3002,
  "message": "The request resource does not exist.",
  "cause": "There is no such user 2ff3c50a-ecdb-47a8-a3b7-35da24a26f20.",
  "docs": "https://developer.permutive.com/docs/errors/400/1000",
  "request_id": "36e3598e-3be0-46b2-a581-ec47aa2aa219"
}

Query Params

user_id
string
required

The ID of the user whose events you wish to retrieve

from
date

Only events that occurred after this time will be retrieved. If no from time is specified, the user's first event onwards will be retrieved.

to
date

Only events that occurred at or before this time will be retrieved. If no to time is specified, events up until the user's most recent will be retrieved.

 

When retrieving a user's events, our API returns a JSON array containing each user event in ascending order of time (i.e. with the most recent event last). Note that this API route is limited to retrieve at most 1000 events in a single call.

Suggest Edits

Introduction to Segments and Queries

 

Segments

Segments process a user's event history and return a state for the given user. They’re created in the Permutive dashboard, then can be accessed through the API or SDK.

For example, you could create a segment of users that have viewed five or more pages. While a user has viewed up to four pages, it would return false, on their fifth, it would return true.

How do I create Segments?

Segments are created in the Permutive dashboard, using the Segment Builder.

Queries

Queries are an advanced feature of Permutive. They allow some advanced use cases not covered by segments. If you're struggling to create a segment that suits your needs, get in touch.

Queries are currently not documented here.

Suggest Edits

Introduction to Triggers and Reactions

 

A reaction is something Permutive does in response to a user's behaviour. This could be adding them to an advertising audience, showing them tailored content, or any other kind of personalisation.

There are two parts to Reactions, the trigger and the reaction itself.

 

Triggers

The particular set of events that should trigger a reaction for a user are specified as a segment. For example, to trigger an overlay when a user has viewed three or more travel-related articles, you create a segment that specifies this user behavior, and then use this segment as your reaction trigger.

We support three types of reaction trigger with respect to the reaction's segment:

  • On entry: the reaction is triggered when the user enters the segment.
  • On exit: the reaction is triggered when the user exits the segment.
  • Every time: the reaction is triggered every time a user visits a page while in that segment.

Here we will break out exactly what each of these means.

On Entry

This will trigger a reaction immediately when a user enters a segment. Segments are evaluated every time an event is received. This means that as soon as an event comes into Permutive that means a user meets segment criteria, the reaction will be triggered.

On Exit

This will trigger a reaction immediately when a user leaves a segment. Segments are evaluated every time an event is received. This means that as soon as an event comes into Permutive that means a user no longer meets segment criteria, the reaction will be triggered.

Every Time

This will trigger a reaction every page load, while a user is in a segment. This means that when a user enters a segment, an 'every time' reaction would not be triggered until their next page load.

Suggest Edits

Types of Reaction

 

There are a variety of different Reactions you can set up in response to your triggers. These are all set up and used in the Permutive Dashboard.

For more information on using them, please see our Support Documentation.

Suggest Edits

Introduction to Users

 

All events in Permutive are tracked against users. Users are allocated unique IDs automatically when using the API or SDK.

It is also possible to assign your Permutive user your own unique ID, which is useful in cases where you know who is using your product. This works well if your product lets users sign-in or identify themselves in some way. By identifying users you can track events across devices.

By calling the identify method on a user, you allocate them your provided custom ID, rather than using a Permutive generated one.

Suggest Edits

Create a User

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.permutive.com/v1.1/users
curl https://api.permutive.com/v1.1/users \
	-H 'X-API-Key: f9975143-2d88-46dc-9247-1fb6c790e1cc' \
  -X POST
A binary file was returned

You couldn't be authenticated

HTTP/1.1 200 OK
{
  "id": "5cd31f9b-2b4e-4d52-92d3-c2ab98d8e50d"
}
 

When you're not using an SDK, Permutive relies on you to store a user's ID. The response returns an object containing the user's ID.

Suggest Edits

User Identities

 

Users are likely accessing your product across lots of different platforms: mobile, desktop, email, and more. You may want to be able to track events across all these devices, and tie them all to the same user. You may also want to store user properties against a user, such as their email address or name. For these purposes, you can use Permutive's identity management.

Permutive tracks events against anonymous UUIDs, until you identify your user with your own unique custom ID, using the API or SDK. When you call identify, you have the option to pass in user properties.

When you identify a user with your own unique custom ID:

  • If we've seen this custom ID before, the anonymous event history is replaced with the event history for that user. On the server-side, an identity will be created. If any user properties are present on the request, the identity will have these properties.
  • If we haven't seen this custom ID before, the anonymous event history is associated with this custom ID. If any user properties are present on the request, they will be appended to the existing identity. If a given user property already exists (e.g. email), then it will be overwritten.

There is a 1:1 mapping of custom IDs to Permutive IDs.

Note that the first time a user is identified, any existing event history will become associated with the user. However if the user has been identified previously, any anonymous event history that was tracked before identify was called will not be associated with your custom ID. This is because Permutive event history is immutable.

Identifying Users

When you identify a user on a new device or browser it is import to call identify as soon as possible, so that events are tracked against your custom ID rather than Permutive's anonymous UUIDs.

Suggest Edits

Identify a User

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.permutive.com/v1.1/identify
curl -XPOST https://api.permutive.com/v1.1/identify \
  -H 'X-API-Key: 3d196f2f-19ba-49f0-8dee-fe51694e960c' \
  -H 'Content-Type: application/json' \
  -d '{
        "id": "5fc70800-c62b-407e-bfbd-12a818555282",
        "custom_id": "josho",
        "properties": {
          "email": "josh@permutive.com"
        }
      }'
A binary file was returned

You couldn't be authenticated

HTTP/1.1 200 OK
{
  "id": "5fc70800-c62b-407e-bfbd-12a818555282"
}

Body Params

id
string
required

The Permutive ID that is currently assigned to the user

custom_id
string
required

Your own ID for the user

properties
object

A map of user properties to write to the identity

 
 

User identification is often done via the SDK, which hides some of the complexity. However identities can also be managed using the API directly.

The identify API call is used for identifying a user with your own custom ID. You pass in the current Permutive ID that is assigned to the user along with your custom ID. The API will create an identity if necessary, and return a Permutive ID for the user.

There are two scenarios:

  1. This is the first time you've called identify with this custom ID. In this case, the API will create a new identity with the Permutive ID you passed in, and will return the same Permutive ID in the response. Any user properties present in the request will be stored against the new identity.
  2. This custom ID has been identified before, and is already linked to a Permutive ID. In this case, the API will lookup and return the existing Permutive ID in the response. Any user properties present in the request will be appended to the existing identity. In the case of a conflict, the user property in the request will overwrite the existing user property.
Suggest Edits

Retrieve an Identity

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.permutive.com/v1.1/identities/custom_id
curl https://api.permutive.com/v1.1/identities/josho \
	-H 'X-API-Key: f9975143-2d88-46dc-9247-1fb6c790e1cc'
A binary file was returned

You couldn't be authenticated

HTTP/1.1 200 OK
{
  "id": "josho",
  "user_id": "5fc70800-c62b-407e-bfbd-12a818555282",
  "properties": {
    "email": "josh@permutive.com",
    "signup_date": "2016-02-14T16:12:31.010Z",
    "company": "Permutive"
  },
  "updated": "2016-03-20T09:44:51.340Z"
}

Path Params

custom_id
string
required

Your ID for the user

 

Private API key required

In order to retrieve identities, you must provide a private API key for authentication.

Suggest Edits

Create an Identity

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.permutive.com/v1.1/identities/custom_id
curl -XPUT https://api.permutive.com/v1.1/identities/josho \
  -H 'X-API-Key: 3d196f2f-19ba-49f0-8dee-fe51694e960c' \
  -H 'Content-Type: application/json' \
  -d '{
        "user_id": "5fc70800-c62b-407e-bfbd-12a818555282",
        "properties": {
          "email": "josh@permutive.com",
          "signup_date": "2016-02-14T16:12:31.010Z",
          "company": "Permutive"
        }
      }'
A binary file was returned

You couldn't be authenticated

HTTP/1.1 200 OK
{
  "id": "josho",
  "user_id": "5fc70800-c62b-407e-bfbd-12a818555282",
  "properties": {
    "email": "josh@permutive.com",
    "signup_date": "2016-02-14T16:12:31.010Z",
    "company": "Permutive"
  },
  "updated": "2016-03-20T09:44:51.340Z"
}

Path Params

custom_id
string
required

Your ID for the user

Body Params

user_id
string
required

The Permutive ID for the user

properties
object

A map of user properties you want to be associated with the identity.

 
 

Note that identities should usually be created via the SDK or identify route. This alternative method of identity creation is intended only to be used server-to-server, using a private API key.

Private API key required

In order to create identities in this way, you must provide a private API key for authentication.

Suggest Edits

Edit an Identity

 

Header Auth

 Authentication is required for this endpoint.
patchhttps://api.permutive.com/v1.1/identities/custom_id
curl -XPATCH https://api.permutive.com/v1.1/identities/josho \
  -H 'X-API-Key: 3d196f2f-19ba-49f0-8dee-fe51694e960c' \
  -H 'Content-Type: application/json' \
  -d '{
        "properties": {
          "email": "josh@permutive.com",
          "signup_date": "2016-02-14T16:12:31.010Z",
          "company": "Permutive"
        }
      }'
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

custom_id
string
required

Your ID for the User

Body Params

properties
object

A map of user properties you want to be associated with the user.

 
 

Currently, only an identity's properties can be edited. Note that this request will replace any existing user properties present on this identity.

Private API key required

In order to edit identities, you must provide a private API key for authentication.

Suggest Edits

Delete an Identity

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.permutive.com/v1.1/identities/custom_id
curl https://api.permutive.com/v1.1/identities/josho
  -X DELETE
  -H 'X-API-Key: 3d196f2f-19ba-49f0-8dee-fe51694e960c'
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

custom_id
string
required

Your ID for the user

 

Private API key required

In order to delete identities, you must provide a private API key for authentication.

Suggest Edits

Python SDK

 

A Permutive SDK has been built by Tails.com, you can find more details about it here.