GuidesRecipesAPI Reference
API Reference
Select productLog inHelp centre

Import contact collection

put
https://{region}-api.dotdigital.com/contacts/v3/import

Imports a collection of contacts. Creates contacts if they do not exist and updates contacts if they do. This is an async operation and you will need to check when it is complete by calling getImportStatus

Note: It isn't possible to specify the value for the contactId field when creating a contact, so it is only used to check for a matching contact when specified


This method allows you submit data in bulk and an asynchronous calling pattern:


The method for polling for import job status is Get import status and once complete also returns the import report showing what contacts were created, updated or failed; this is also when you can capture the contactId for each contact sent to Dotdigital Marketing.

📘

Phone numbers

Phone numbers must be in international format (E.164); Google have a good library for reformatting phone number called libphonenumber which has been ported to most languages.

📘

Import limits

Your JSON request body can be a maximum size of 50MB, therefore allowing a large number of contacts to be imported in a single call.

Active contact imports are limited to 25. If you exceed this limit, you get the Too many active imports error.

🚧

Specifying null for a data fields value clears the field

You must ensure that you only pass the fields you require to be updated for a contact.

We interpret a field passed with a null value as an instruction to clear the value for that field.

This only works with data fields in this call, not identifiers.


Body Params

Contact data collection

string
enum
Defaults to overwrite

Specify how the merging of new data with existing data is handled

Allowed:
contacts
array of objects
required
length ≥ 1
contacts*

The contact data

string
required

Specify which identifier in the provided identifiers should be used to match the contact to an existing record. This can be a custom identifier or a contact identifier of contactId, email or mobileNumber.

identifiers
object
required

Identifiers this contact can be referenced by

dataFields
object

Addtional data fields for the contact

channelProperties
object

Properties associated with each channel for a contact. For example, message format or subscription status

lists
array of int32s
length between 1 and 100

List IDs for the lists the contact should be added to

lists

Unique list id

preferences
array of objects
length ≥ 1

Preferences you want to opt the contact into. Note: Only required for preferences and not preference categories

preferences
int32
required

ID of the preference

boolean
required

Specify whether the contact is opted into this preference

consentRecords
array of objects
length between 1 and 5

The marketing consent records to be associated with the contact

consentRecords

Marketing consent records to be associated with the contact

string
required
length ≥ 1

Consent text displayed to the contact

date-time
required

ISO 8601 UTC timestamp for when the consent was obtained

uri
required

URL the consent was obtained with

required

IPv4 address of the contact the consent was obtained for

string
required
length ≥ 1

User agent header of the browser used by the contact the consent was obtained for

Headers
string

If you are a partner of Dotdigital and have a verified integration then include your integration tracking token here.

Responses

401

Unauthorized

Updated 6 days ago

Language
Credentials
Basic
base64
:
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 6 days ago