Statistics API

Content

• Introduction
  • Versioning
  • Authentication
  • Date Format
  • Error handling
• Reference
  • KPI management
  • Statistics
  • Entity types
  • Formula
  • KPI names
  • Channels
  • Aggregation

Introduction

The Statistics API is designed to help you synchronously access all story, campaign & message statistics performance data available in ActivatePro.

Versioning

The versions of our different endpoints are defined in the header X-XNG-ApiVersion. To use this API please provide version 2.

Authentication

ActivatePro uses header authentication. To get your API key, please log into the app and navigate to Settings. You will find the value in the System setup -> API keys section in the Public API key. For example:

• X-XNG-AuthToken: 3fe00023932f9903

Date format

Dates and times are expressed in ISO8601 format in UTC (Coordinated Universal Time), with a special UTC designator ("Z") For more information please check here.

Error handling

When exporting data from ActivatePro, please use the below practices related to error handling:

Resume or retry uploads that fail due to connection interruptions or any 5xx errors, including:

• 500 Internal Server Error
• 502 Bad gateway
• 503 Service Unavailable
• 504 Gateway Timeout

How to retry requests made to ActivatePro in case of errors:

• Use an exponential backoff strategy if any 5xx server error is returned when retrying export requests. These errors can occur if a server is getting overloaded. Exponential backoff can help alleviate these kinds of problems during periods of high volume of requests or heavy network traffic.
• Other kinds of requests should not be handled by exponential backoff but you can still retry a number of them. When retrying these requests, limit the number of times you retry them. For example your code could limit to ten retries or less before reporting the error to our team for investigation.

Reference

KPI management

GET https://api.crossengage.io/statistics/kpi

Content-Type:application/json
X-XNG-ApiVersion:2
X-XNG-AuthToken:Your API Key

Content-Type:application/json

[
  {
    "id": "213",
    "name": "Conversion to View Rate",
    "formula": "CONVERSION / UNIQUE VIEWED * 100",
    "type": "PERCENTAGE",
    "createdAt": "2015-08-05T08:40Z",
    "updatedAt": "2015-08-05T08:40Z"
  }
]

Use this endpoint to get all of the KPIs available on your account and their details.

GET https://api.crossengage.io/statistics/kpi

Content-Type:application/json
X-XNG-ApiVersion:2
X-XNG-AuthToken:Your API Key

Content-Type:application/json

{
  "id": "213",
  "name": "Conversion to View Rate",
  "formula": "CONVERSION / UNIQUE VIEWED * 100",
  "type": "PERCENTAGE",
  "createdAt": "2015-08-05T08:40Z",
  "updatedAt": "2015-08-05T08:40Z"
}

Use this endpoint to get the details of a certain KPI by ID.

Statistics

GET https://api.crossengage.io/statistics/detailed

Content-Type:application/json
X-XNG-ApiVersion:2
X-XNG-AuthToken:Your API Key

{
  "entities": [
    {
      "id": "245",
      "channel": "MAIL",
      "type": "CAMPAIGN_CHANNEL"
    }
  ],
  "kpiIds": [
    "1",
    "12"
  ],
  "interval": {
    "startDate": "2019-09-01T00:00:00Z",
    "endDate": "2019-09-30T23:59:59Z"
  },
  "aggregation": "WEEK"
}

Content-Type:application/json

{
  "interval": {
    "startDate": "2018-08-24T00:00:00Z",
    "endDate": "2018-08-24T23:59:59Z"
  },
  "detailed": [
    {
      "entity": {
        "id": "245",
        "channel": "MAIL",
        "type": "CAMPAIGN_CHANNEL"
      },
      "startDate": "2018-08-24T00:00:00Z",
      "endDate": "2018-08-24T23:59:59Z",
      "kpi": {
        "23": "100.0",
        "25": "80.0",
        "31": "NaN"
      }
    }
  ],
  "overall": [
    {
      "entity": {
        "id": "245",
        "channel": "MAIL",
        "type": "CAMPAIGN_CHANNEL"
      },
      "startDate": "2018-08-24T00:00:00Z",
      "endDate": "2018-08-24T23:59:59Z",
      "kpi": {
        "23": "100.0",
        "25": "80.0",
        "31": "NaN"
      }
    }
  ]
}

Use this endpoint to get statistics for certain entity IDs (story, campaign or message ID) on your account according to a variety of aggregation options.

Please note that, according to the time interval you request in conjunction with the aggregation, our system will expand your requested interval to fit as many aggregations as possible. Please see the examples below:

Requesting an interval from 2018-08-24T00:00:00Z to 2018-08-26T23:59:59Z with a MONTH aggregation would return data from 2018-08-01T00:00:00Z to 2018-08-31T23:59:59Z (returning the entire month of August 2018).

Requesting an interval from 2018-08-24T00:00:00Z to 2018-08-31T23:59:59Z with a WEEK aggregation would return data from 2018-08-20T00:00:00Z to 2018-09-02T23:59:59Z (returning calendar Week 34 and 35 of 2018).

POST https://api.crossengage.io/statistics/overall

Content-Type:application/json
X-XNG-ApiVersion:2
X-XNG-AuthToken:Your API Key

{
  "entities": [
    {
      "id": "245",
      "channel": "MAIL",
      "type": "CAMPAIGN_CHANNEL"
    }
  ],
  "kpiIds": [
    "1",
    "12"
  ],
  "interval": {
    "startDate": "2018-08-24T00:00:00Z",
    "endDate": "2018-08-24T23:59:59Z"
  }
}

Content-Type:application/json

Show JSON Schema
[
  {
    "entity": {
      "id": "245",
      "channel": "MAIL",
      "type": "CAMPAIGN_CHANNEL"
    },
    "startDate": "2018-08-24T00:00:00Z",
    "endDate": "2018-08-24T23:59:59Z",
    "kpi": {
      "23": "100.0",
      "25": "80.0",
      "31": "NaN"
    }
  }
]

Use this endpoint to get overall statistics for certain entity IDs (story, campaign or message ID) on your account according to a particular time interval or since the first dispatch of a selected entity until the present.

Entity types

Formula