API client

After embedding the Piano javascript file on your pages, the browser will have a built-in javascript REST API client. From here, you can call all of our API endpoints. However, you should never call any /publisher* endpoints from any client-side implementation.

Note: Your API token should be treated like a password and never shared with end users - either by embedding it in the browser or native mobile applications.

Making Your First Call

After the Piano javascript loads, you can fire up your javascript console and make your first API request.

tp.push(["init", function() {
    var params = {
        first_parameter : "value1",
        second_parameter : "value2"
    }
    tp.api.callApi("/endpoint", params, function(response) {
        // the response object contains the full json object
        // you can check response.code to determine success
    });
}]);

Endpoints

There are four publicly-available API methods that can be called by the browser. There is no need to pass the encrypted user ref or janrain capture token to these methods directly. If you have previously set the user ref, there is no need to include this value in the params object. Similarly, there is no need to include your AID in the parameters as long as you have already set the AID in your initialization code.

If you are using janrain, we will collect the capture token automatically for logged-in users when submitting the API request. There is no need to collect this information from local storage directly.

List Conversions

The /conversion/list method will return back the list of conversions that the particular user (or browser) has converted on.

tp.push(["init", function() {
    var callback = function(response) {
        console.debug(response);
    }
    tp.api.callApi("/conversion/list", {}, callback);
}]);

A sample response is:

  {
      "code": 0,
      "ts": 1234567890,
      "conversions": [{
          "term_conversion_id" : "TCU0US9OY165",
          "term" : {
            "aid" : "MODETWOAPP",
            "term_id" : "TMI834Q1BJAC",
            "resource" : {
              "rid" : "RID",
              "aid" : "MODETWOAPP",
              "name" : "Test Resource",
              "description" : null,
              "image_url" : null
            },
            "name" : "Subscription with trial for new customers only",
            "description" : "description",
            "type" : "payment"
          },
          "aid" : "MODETWOAPP",
          "type" : "subscription",
          "user_access" : {
            "access_id" : "XYvuSmviyhHG",
            "granted" : true,
            "resource" : {
              "rid" : "RID",
              "aid" : "MODETWOAPP",
              "name" : "Test Resource",
              "description" : null,
              "image_url" : null
            },
            "user" : {
              "first_name" : "first",
              "last_name" : "last",
              "email" : "[email protected]",
              "uid" : "[email protected]"
            },
            "expire_date" : 1434835221
          },
          "create_date" : 1432156822
      }]
  }

Checking Access

The /access/check method will perform an access check for a specific resource. This method accepts a single parameter rid that corresponds to the resource that the access check is being performed against.

tp.push(["init", function() {
    var params = {
        rid : "PREMIUM_ACCESS"
    };
    var callback = function(response) {
        console.debug(response);
    }
    tp.api.callApi("/access/check", params, callback);
}]);

A sample response is:

{
    "code": 0,
    "ts": 1234567890,
    "access": {
        access_id: "The unique access id"
        granted: true,
        expire_date: 1234567890,
        resource: {
            rid: "PREMIUM_ACCESS",
            name: "Resource name",
            aid: "AID",
            description: "Resource description",
        },
        user: {
            first_name: "User's first name",
            image1: "User's profile image",
            email: "User's email address",
            last_name: "User's last name",
            uid: "uid",
            create_date: 1234567890
        }
    }
}

You can check the granted boolean to determine if the user has access or not.

You should not rely on code to be non-zero in the case where the user doesn't have access. The API request is still considered valid, and you need to inspect the response to determine whether the user actually has access.

List Access

The /access/list method will list the active access that a user has access to. This will return an empty array if the user doesn't have any active access to any resources.

tp.push(["init", function() {
    var params = {
        rid : "PREMIUM_ACCESS"
    };
    var callback = function(response) {
        console.debug(response);
    }
    tp.api.callApi("/access/list", params, callback);
}]);

A sample response is:

{
    "code": 0,
    "ts": 1234567890,
    "accesses": [{
        access_id: "The unique access id"
        granted: true,
        expire_date: 1234567890,
        resource: {
            rid: "PREMIUM_ACCESS",
            name: "Resource name",
            aid: "AID",
            description: "Resource description",
        },
        user: {
            first_name: "User's first name",
            image1: "User's profile image",
            email: "User's email address",
            last_name: "User's last name",
            uid: "User's UID",
            create_date: 1234567890
        }
    }]
}

You can check the granted boolean to determine if the user has access or not.

You should not rely on code to be non-zero in the case where the user doesn't have access. The API request is still considered valid, and you need to inspect the response to determine whether the user actually has access.

Access Token List

The /access/token/list method will return the encrypted access token list.

Subscription List

The /subscription/list method will return all of the currently logged in user's subscriptions.

tp.push(['init', function() {
    tp.api.callApi('/subscription/list', {}, function(response) {
        console.debug(response);
    });
}]);

This will return something like this:

{
  "code" : 0,
  "ts" : 1444941958,
  "limit" : 1,
  "offset" : 0,
  "total" : 1,
  "count" : 1,
  "subscriptions" : [ {
    "subscription_id" : "RC0VND69EZYW",
    "auto_renew" : true,
    "next_bill_date" : 1447464861,
    "payment_billing_plan_description" : "$299.99 per year / free trial for 30 days",
    "status" : "active",
    "cancelable" : true,
    "cancelable_and_refundadle" : false,
    "term" : {
      "aid" : "wEdSwjGGTo",
      "term_id" : "TMHIUCWF1TGE",
      "resource" : {
        "rid" : "PREMIUM",
        "aid" : "wEdSwjGGTo",
        "name" : "Pro Subscription",
        "description" : "Premium Access Resource",
        "image_url" : "/images2/default/file-document.png"
      },
      "name" : "Annual Plan",
      "description" : "",
      "type" : "payment",
      "create_date" : 1442609590
    },
    "start_date" : 1444872861
  } ]
}

If the user is currently in a grace period, the grace_period_start_date will be populated.

{
  "code" : 0,
  "ts" : 1444941958,
  "limit" : 1,
  "offset" : 0,
  "total" : 1,
  "count" : 1,
  "subscriptions" : [ {
    "subscription_id" : "RC0VND69EZYW",
    "auto_renew" : true,
    "next_bill_date" : 1447464861,
    "payment_billing_plan_description" : "$299.99 per year / free trial for 30 days",
    "status" : "active",
    "cancelable" : true,
    "cancelable_and_refundadle" : false,
    "grace_period_start_date": 1447464861,
    "term" : {
      "aid" : "wEdSwjGGTo",
      "term_id" : "TMHIUCWF1TGE",
      "resource" : {
        "rid" : "PREMIUM",
        "aid" : "wEdSwjGGTo",
        "name" : "Pro Subscription",
        "description" : "Premium Access Resource",
        "image_url" : "/images2/default/file-document.png"
      },
      "name" : "Annual Plan",
      "description" : "",
      "type" : "payment",
      "create_date" : 1442609590
    },
    "start_date" : 1444872861
  } ]
}

You can use this value to target a particular user with an offer to check that their credit card is valid and up-to-date.