REST - Statistics Export

Introduction

Many customers have the need to export contacts and miscellaneous data from Carma.

A brief overview of RESTful web services can be found here:

http://net.tutsplus.com/tutorials/other/a-beginners-introduction-to-http-and-rest/

General workflow

  • In order to start an export you must decide which data you want and for how long timeperiod you want it. As the data is on a per message basis the file can get big if you you choose to big a timespan. The recommended way is to export data once a day.

Possible timeperiod values are: 

  • TODAY,
  • LAST_DAY
  • LAST_3_DAYS
  • LAST_WEEK,

Possible export values are:

  • LISTS
  • CAMPAIGNS
  • MESSAGES
  • OPENS
  • SENT
  • CLICKS
  • PROJECTS
  • HARD_BOUNCES
  • SOFT_BOUNCES
  • OPTOUTS

The two values should be put into a json struct that will be sent with the POST request.

  • After all of this information have been gathered it’s time to make the request. The response, if everything went well, will contain a unique id that will be used later.To start the export  a POST request with metadata describing the import is sent:

    POST <server>/rest/<customerId>/batches/exports/statistics

{

“exportType”: “OPENED”,

“period”: “LAST_2_WEEKS”

}

Example response body
{
“batchId”: “101111”

}

  • You can query the API to trace the export progress. Use the batchId from the previous request:

GET <server>/rest/<customerId>/batches/<batchId>

Response body

{

“id”: 101111,

“type”: ” STAT_EXPORT”,

“customerId”: 0,

“startTime”: 1394636797030,

“endTime”: 1394636799710,

“affected”: 500,

“processed”: 500,

“total”: 501,

“status”: ” PENDING|IN_PROGRESS|FINISHED”

}

  • When you get a status=FINISHED the file is available for retrieval.

GET <server>/rest/<customerId>/batches/<batchId>/result/url

This will result in an URL that you can use to retrieve the exported file. The url will look something like this:

https://carma-filetransfer.s3-eu-west-1.amazonaws.com/result/5004/3232465_result.json?Expires=1403187484&AWSAccessKeyId=AKIAJNJRZJQCQ3W66YIQ&Signature=FWZp8noVyxcOflH27k2W7MuNcmM%3D

NOTE! The return data is in text/plain, so make sure you do not use application/json as the Accept header for the call.

You can also use the following URL to get redirected to the result stored on amazon s3.

GET <server>/rest/<customerId>/batches/<batchId>/result