GuidesRecipesAPI Reference
API Reference
Select productLog inHelp centre

Import a single contact

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

Imports a single contact; if it is an existing contact it updates the contact with just the fields passed in the request with a choice of how to handle the merging of data, otherwise it create a new contact.

📘

Request behavior

The identifier specified in the URL path is used to uniquely identify a contact. This can be a custom identifier or a system contact identifier; contactId, email, or mobileNumber.

Existing contacts

When we find a contact in the account with the specified identifier, the contact record is updated with any data supplied in the object in the request body.

Deleted contacts

When we find a contact in the recycled bin with the same identifier that you pass in, we will undelete the contact and update with the passed details.

New contacts

If no contact is found with the provided identifier, the contact is created using the identifiers supplied in the object in the request body. The object must contain either an email address or mobile number in the identifiers field.

🚧

Specifying null for a field's value clears the field

Only pass the fields you require updating for a contact.

We interpret a field passed with a null value (in other words, an empty field) as an instruction to clear the value for that field.

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

Path Params
string
required
length between 1 and 50

The field to use to uniquely identify the contact. This can be a custom identifier or a contact identifer of contactId, email or mobileNumber

string
required
length between 1 and 256

The unique value to identify the contact.
Note: Must be the same type as the identifier

Query Params
string
enum
Defaults to overwrite

Set the behavior of how the new data should be merged into existing contacts.

Allowed:
Body Params

The contact fields to update. Note: It is not possible to modify the contactId field

identifiers
object

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