Bulk creates, or bulk updates, contacts from a file
This operation bulk creates, or bulk updates, contacts in the import file.
Batch Calling Pattern
This method allows you submit data in bulk and works as part of the following 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.
File format
The import format can either be CSV or Excel. It must include one column called 'Email' (casing is not important). Any other columns will attempt to map to your custom contact data fields.
As shown in the code examples above, the server requires you to provide the filename
parameter of the Content-Disposition
header in the multipart body. Without this header, you'll receive the response { message: 'file must be valid' }
with a HTTP 400
status code.
Passing consent
You'll need to specify the following additional column headers in your file in order to successfully import consent:
- CONSENTTEXT
- CONSENTURL
- CONSENTDATETIME
- CONSENTIP
- CONSENTUSERAGENT
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"
}
File submission
You can call the method using either a JSON request (content-type: application/json) with the file data in base64 format, or by passing a file using a multipart form (content-type: multipart/form-data)
When using multipart form submissions
If using a multipart form submission to send the file, the server requires you to provide the
filename
parameter of theContent-Disposition
header in the multipart body. Without this header, you'll receive the response{ message: 'file must be valid' }
with aHTTP 400
status code. e.g.Content-Type: multipart/form-data; Content-Disposition: form-data; name="contacts.csv"; filename="/C:/Example/contacts.csv"
Request Limits
There is a 50MB file upload limit; if your file is larger than this, please break your upload into separate files.
Response
The ID of the returned object can be used to query import progress.
The possible status types 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
- 'InvalidFileFormat' - The file imported was not in the advised CSV or Excel format
- '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