Bulk import contacts collection

Bulk creates, or bulk updates, contacts from JSON

This operation bulk creates, or bulk updates, the contacts passed in the JSON.

Batch Calling Pattern

This method allows you submit data in bulk and works as part of the following calling pattern:


Bulk data upload calling pattern

The method for polling for import job status is Get contact import status and the methods for getting the import job reports are Get contact import report and Get contact import report faults


Active contact imports are limited to 25

If you exceed this limit, you'll get the 'too many active imports' error.

Identifying Contacts

Each contact record must specify either an id field for the contact or an email field; if both are specified then the id field will be used. Any specified data fields will attempt to map to your custom contact data fields.

Passing Preferences

To pass marketing preference for a contact you must create a specifically formatted key value pair and pass it within the contacts dataFields array. The key is used to identify the preference to be set, and the value is a boolean (True or False). The key name should be formatted as follows:

Preference: {Preference name or category}[ > {Preference name}]*

Setting a top level preference

Preference:{Preference name}

Setting a preference in a category

Preference:{Category name}>{Preference name}

  "key": "Preference:MonthlyUpdates",
  "value": "False"
  "key": "Preference:Marketing>Offers",
  "value": "True"

Request Limits

There is a 50MB request limit; if your data is larger than this, please break your upload into separate calls.


The ID of the import job is returned in the response and can be used to query import progress.

The possible status values are:

  • 'Finished' - The import has been accepted and has successfully imported
  • 'NotFinished' - The import has been accepted, but has not yet finished.
  • 'RejectedByWatchdog' - The import was rejected by Watchdog due to concerns with the quality of your email data; please contact support
  • 'Unknown' - The import has an unknown state which could indicate an invalid import ID; please contact support
  • 'Failed' - The import has failed; please contact support
  • 'ExceedsAllowedContactLimit' - The contacts you're trying to import exceeds your account's contact limit
  • 'NotAvailableInThisVersion' - This feature is not available in the version of the API you're using

You can query the status of your import using the id returned and by calling Get contact import status

Click Try It! to start a request and see the response here!