Public Preview
This service is in public preview.
This means that the API is ready to use, but it may be subject to change as we refine it.
We’d appreciate your feedback about your experience using the API to help us continue to improve it.
The new Dotdigital
Dotdigital has undergone a major evolution in the way you can work with and analyse your data. A huge part of this change is the introduction of unified contacts.
Understanding unified contacts
Dotdigital has offered the opportunity to engage with contacts using email and SMS for some time, however the contacts for each of these channels were isolated, preventing you from using the same address books and segments for both email and SMS communications. Unified contacts bring your data together so that a single contact can have multiple communication channel identifiers stored against it. A unified contact can be created with either an email address, mobile number or both.
How contacts have been merged into unified contacts
How to reference a unified contact
When you create a contact in Dotdigital we pass back a unique, immutable contactId which you should retain in your system. This contactId is the most reliable way to refer to a contact, because it doesn’t change. This allows you to update any other identifiers associated with the contact.
In our new Unified Contacts compatible service we offer a flexible method of referencing a contact. You can refer to a contact using anyone of the following identifiers but you must specify which one you are using in the API call:
- Contact ID
- Mobile number
Referencing a contact using an identifier type and value
What else has changed?
Channel subscription behavior
API v2 email centric behavior
API v2 is email centric and considers a contact as a single entity with the main identifier being the email address. If a contacts email channel status becomes unsubscribed or suppressed, then updates to the contact via API v2 are not processed as in the email centric world the changes are no longer relevant.
How does Unified Contacts differ?
API v3 (Unified Contacts), is designed for our CXDP functionality and therefore allows the updating of contact data independent of any channels status, as no assumptions are made on how or why you are storing the contacts data.
This means that for API v3 (Unified Contacts) we do allow a contact's data fields to be updated even where they are suppressed, without the necessity of changing the contact's channel status(es) - we do not reject any updates because they are suppressed. Updating a suppressed contact will succeed and the contacts channel statuses will remain unchanged unless otherwise stated in the update.
Address books are now lists
To align with wider industry terminology, and to reflect the greater variety of data you can store, address books have been renamed to lists. The functionality for lists is identical to the way you are used to working with address books. Any of your existing address books are automatically available as lists, with the same names and unique numeric ids.
Address books are referred to as lists with unified contacts