REST - List Import

Introduction

Many customers have the need to import contacts and miscellaneous data into Carma.  In order to get started basic knowledge of Carma’s list and contact management is required. Readers are assumed to have some familiarity with Carma’s graphical interface.

General workflow

  • In order to start an import you will need to prepare a file. Carma uses plain text[1] as input. If your recipients are saved in an Excel document you must save the data as txt. The information in the file must be stored in tabular format delimited by comma, tab or any other appropriate character. In Carma under Account Settings > Profile Attributes you can manage how the fields in the file are mapped to your contacts properties.
  • After the file has been prepared it’s time to make the first request to the API. You will need four things four this request:
  1. The ID of the list in Carma where you want to save your contacts,
  2. The ASCII value of the delimiter used in the file,
  3. The encoding of the file the
  4. The type of import you want to run.

There are three types of imports:

  1. Add, adds all the contacts in you file to the existing list
  2. Replace, replaces all contacts in the list with the ones in you file
  3. Unsubscribe, set all contacts that have matching rows in the file to unsubscribed

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 import a POST request with metadata describing the import is sent:

POST <server>/rest/<customerId>/lists/<listId>/imports

{

“delimiter”: “9”,

“encoding”: “UTF8”,

“type”: “REPLACE”

}

Example response body
{
“id”: “bd48b5cc-b118-4062-8d06-09efa765592b”

}

  • There is a special feature that can be activated in the step described above. This feature is called Identity Column and it will let you specify how the fields in you file are mapped to the contacts identity in Carma. Normally you will have to provide a column with a unique identifier (called originalId in Carma). This could be a row number, primary key, customer number or something else that uniquely identifies this contact.  If you can’t provide a column of this sort you can use email address, mobile number or any other column in you file as identifier. Here is an example using this feature:

POST <server>/rest/<customerId>/lists/<listId>/imports
{

“delimiter”: “9”,

“encoding”: “UTF8”,

“type”: “REPLACE”,

“identityColumn”: “emailaddress”

}

  • After the initial request have been made and an ID have been returned it’s time to upload your data. Use the id obtained in the response of the first request to upload your data:POST <server>/rest/<customerId>/lists/<listId>/recipients/<id>

CONTENT-TYPE: text/csv

<data from file>

 

Example response body
{
“batchId”: “101111”

}

  • When the file has successfully been uploaded you can query the API to trace the imports progress. Use the batchId from the previous request. You can keep polling the method until you receive a response with the status set to “FINISHED”.  Do not poll too often as that will put unnecessary strain on the system. Polling once every 30 seconds or every minute is normally sufficient.

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

Response body

{

“id”: 101111,

“type”: “IMPORT”,

“customerId”: 0,

“startTime”: 1394636797030,

“endTime”: 1394636799710,

“affected”: 500,

“processed”: 500,

“total”: 501,

“status”: ” PENDING|IN_PROGRESS|FINISHED”

}