Understanding unified contacts

Unified contacts allows contacts to have multiple communication channel identifiers stored against it, as well as any data you need to store. A unified contact can be created with either an email address, mobile number or both.

How to reference a 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.

Our contacts service offers 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 to match on:

Contact ID
Email
Mobile number ( In international format E.164 )
Custom identifiers

Referencing a contact using an identifier type and value

Channel subscription behavior

Dotdigital is designed for 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 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.

Note:

When you add a phone number, at least one mobile channel must have a different value than noSubscription, you can set defaults in Settings > Contacts > Mobile subscription
You can't update a mobile number if either SMS or WhatsApp is suppressed or unsubscribed.

How to update a channel subscription status

Our contacts API's support updating a contacts subscription for one or more channels in the various update calls via the channelProperties field. We recommend using Import contact collection for bulk updates and Import a single contact for individual updates.

Using lists with contacts

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

Adding contacts to lists

You need to use the Contacts API to add contacts to lists; we recommend using Import a single contact for individual updates and Import contact collection for bulk operations. The lists field can be used to specify up to 100 list ids to add a contact to.

Finding contacts in lists and segments

Since Dotdigital adopted unified contacts that can be identified using any associated identifier, such as email, mobile number, contact id etc..., it is important to use the Contacts API for interacting with any contacts. You should use the Get contacts based on your criteria call with the ~listId filter to find contacts in a list, and the ~segmentId can be used for segments.

Finding modified contacts in a list or segment

We recommend using the Get contacts based on your criteria with the ~modified filter used in conjunction with either the ~listId filter or the ~segmentId to find contacts modified after a specific date-time in a list or segment.

Contact deletion

In order to afford customers the opportunity to restore contacts that they have been engaging with, we run a staged removal of contact data and their related data.

Deletion stage 1 - Soft delete and binned

Whenever a contact is deleted in app or via API the contact in put into the recycle bin and the contact status is updated to binned.

The handling of binned contacts differs depending on the contacts channel subscription status:

Contacts subscribed to at least one channel

Will be stored in the recycle bin for up to 30 days at which point they will move to deletion stage 2 to be hard deleted and anonymized.

Suppressed contacts, no subscriptions on any channel

Will immediately move to deletion stage 2 to be hard deleted and anonymised.

🚧
Emptying the recycle bin
If the recycle bin is emptied in app or via API using Empty recycle bin call then all binned contacts will immediately proceed to deletion stage 2 for hard deletion and anonymization.

Deletion stage 2 - Hard delete and anonymization

At this stage a contact is hard deleted and any data we cannot delete is anonymized.

Data that is hard deleted includes:

all data on the contacts record
data fields
channel data
contact scoped all insight data

Note: We will retain any suppressed/unsubscribed channel identifiers to ensure that the unsubscribe is retained.

The contacts channel identifiers and engagement statistics are anonymized.

❗️
Hard deleted contacts cannot be recovered
Once contacts have left the recycle bin and proceeded to be hard deleted and anonymized they cannot be recovered.

Contact restoration

If a contact is in the recycle bin (status binned) they can be restored in app manually or if you import via API a contact with at least one identifier with the same value as a binned contact.