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!

API Reference

Privacy and GDPR

As your data processor, Permutive provides a number of methods to help you comply with privacy standards and upcoming GDPR regulations.

These are documented below, and as regulations and requirements change, this document will continue to be updated. If you have any questions, please email


By default, Permutive assumes the data controller has consent to track their users’ data, which we call consent-by-default. In this configuration mode, collection of user data starts the first time Permutive’s SDK loads without requiring a consent token be passed by the controller for the user.

As a data controller, you may need to receive consent from the user before tracking data against them. Permutive offers data processors a consent mechanism for this use-case, which we call consent-by-token. In this configuration mode, no user data is collected until the data controller has received consent from the user and passed the user’s consent token to the Permutive SDK. Once the Permutive SDK has been granted consent for this user, the SDK will start collecting user data from this moment on. The user can revoke this consent at any point.

To configure your Permutive SDK in consent-by-token mode, set the consentRequired configuration field to true:

  !function(n,e,o,r,i){ ... }(document, window.permutive, PROJECT_ID, API_KEY, { "consentRequired": true });
  permutive.addon("web", { page: {
    // ...

No user data will be tracked by the SDK until it receives a consent token for the user. Once you have obtained consent for the user, consent can be passed to Permutive by calling the SDK consent method with the consent token as below. From this point on, the SDK will track user event data — or until the user wishes to opt out.

permutive.consent({ "opt_in": true, "token": "YOUR_CONSENT_TOKEN_HERE" });

SDK version

To use consent functionality, you must update your Permutive SDK to at least version 2.3.0. If you implemented Permutive before May 2018, please get in touch for assistance with updating your tag.


You may choose or be required to offer users the option to opt out of tracking. All future tracking is then disabled for the user until the point they opt back in.

Whether the SDK is configured in consent-by-default or consent-by-token mode, a user can be opted out by setting the consent opt-in field to false:

permutive.consent({ "opt_in": false });
if (!window.localStorage.getItem("permutive-opt-out")) {
  !function(e,n,t,r,o,i){if(!n){n=n||{},window.permutive=n,n.q=[],n.config=i||{},n.config.projectId=r,n.config.apiKey=o,n.config.environment=n.config.environment||"production";for(var c=["addon","identify","track","trigger","query","segment","segments","ready","on","once","user"],a=0;a<c.length;a++){var p=c[a];n[p]=function(e){return function(){var,0);n.q.push({functionName:e,arguments:t})}}(p)}var s=window.Worker?"async":"blocking",g=e.createElement("script");g.type="text/javascript",g.async=!0;var f=("https:"==e.location.protocol?"https://":"http://")+"";g.src=f+"/"+r+"-"+s+".js";var m=e.getElementsByTagName(t)[0];m.parentNode.insertBefore(g,m)}}(document,window.permutive,'script',"PROJECT_ID","API_KEY",{});

The consent opt-in field can be set to true to opt the user back in. If the SDK is in consent-by-token mode, a consent token will also need to be supplied (see Consent section above).

GDPR rights

Under upcoming GDPR regulation, you will be expected to comply with a number of key "rights". With respect to Permutive, these are:

  • The right of access
  • The right of erasure
  • The right to data portability

Guide to GDPR

For a detailed break down of these, and other rights, please see the UK's Information Comissioner's Office's Guide to GDPR

The right of access

As part of the right of access, "individuals have the right to access their personal data and supplementary information."

As a data controller, this means you need to be able to show a user their event history within the browser. Permutive provides an API endpoint, which allows you to retrieve a user's data and render it in real-time.

permutive.ready(function () {
    var url = "" + permutive.context.user_id + "&api_key=" + permutive.config.apiKey;

    function handler() {
        var data = JSON.parse(this.responseText);
        // do something with data

    var req = new XMLHttpRequest();
    req.addEventListener("load", handler);"GET", url, true);

The right of erasure

The right of erasure, or the right to be forgotten, allows "an individual to request the deletion or removal of personal data where there is no compelling reason for its continued processing".

As a data controller, this means you need to be able to delete the link between a user's browser and the data stored within Permutive. Permutive enables you to do this via a simple JavaScript method.


The right to data portability

The right to data portability "allows individuals to obtain and reuse their personal data for their own purposes across different services".

As a data controller, this means "you must provide the personal data in a structured, commonly used and machine readable form". Permutive enables you to do this via an API endpoint which provides the user's data in a machine readable format (JSON).

permutive.ready(function () {
    var url = "" + permutive.context.user_id + "&api_key=" + permutive.config.apiKey;
  // Render the URL or setup a link to it
permutive.ready(function () {
  var url = "" + permutive.context.user_id; 
  // Update the download data link to point at the user's data
  $("a#download-data").attr("href", url);