API database import

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

General workflow

Batch imports triggered by the API adds an overhead to each included file. You should therefor send larger files less often, rather than smaller files frequently.
Recommended minimum import interval is hourly but a new import should not be initiated until a previous import is done (check the batch status).

If import files are triggered too frequently, the service will respond with a HTTP 429. Your import may also be throttled and placed in queue. In other words, several sequentially imported files will cause an import delay.

Please observe these recommendations to avoid issues.


Preparing your file

In order to start an import you will need to prepare a file. Symplify 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 Symplify, on Account Settings > (Audience) Recipient Attributes, you can manage how the fields in the file are mapped to your contacts properties.


Making the first request

After the file has been prepared it’s time to make the first request to the API. You will need four things for this request:

  • The ID of the list in Symplify where you want to save your contacts
  • The ASCII value of the delimiter used in the file
  • The encoding of the file
  • The type of import you want to run.

There are three types of imports:

  • Add: adds all the contacts in you file to the existing list
  • Replace: replaces all contacts in the list with the ones in you file
  • 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 your file are mapped to the contacts identity in Symplify. Normally you will have to provide a column with a unique identifier (called originalId in Symplify). 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”

Uploading your data

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”}


Check batch status

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,


[1] UTF8, UTF16, ISO-8859-1, ANSI are also supported.

Was this article helpful?
0 out of 0 found this helpful