Customers with multiple profiles - merging profiles

Note: For information about forcing a profile merge with dedicated endpoints, see Merging profiles with the API.

Sometimes, multiple profiles refer to the same customer. In that case, they need to be merged.
In such cases, a number of source profiles are merged into a target profile. The source profiles are deleted after merging.
In the cases described in this article, the system determines which profile is the target. If you want to force a particular profile to be the target, use the dedicated merge endpoints.

Merging profiles is irreversible. The deleted profiles can’t be recovered.

After the merge is complete, a client.merge event is saved to the target profile.

Merging overview

A request that causes some kind of a profile update uses identifiers that match multiple profiles (other than clientId).
In most cases, only two profiles are involved.
Data of all the matching profiles is pulled from the database.
The system determines the target profile automatically.
If you want to force the selection of the target profile, use the dedicated endpoints.
Data is moved from source profiles to the target profile.
Attributes that don’t exist in the target profile are copied. Properties and tags from source profiles are lost. See “Properties, tags, and attributes”.
Assign identities (UUIDs) to target profile. This connects the event history of the source profiles to the target profiles.
The source profiles are deleted.
The original update request is processed.

Merge triggers

Profiles may be merged when an update request includes identifiers (other than clientId) of multiple profiles in the following situations:

Profiles are imported with simple imports.
Profiles are imported with the “Import profiles” Automation node.
A POST request is made to /v4/clients
Profiles are updated with the batch create/update request (/v4/clients/batch), including multiple updates of the same profile. Each element of a batch request is processed separately. For example, if three objects in a batch cause a merge of a profile, the result is three subsequent merge operations.
Profile create/update requests are made by the Web SDK with the sendFormData method.
One of the following events is sent:
- client.createOrUpdate
- client.login
- form.submit
- page.visit, screen.view, client.applicationStarted: can only merge anonymous profiles

Examples

A customer visited your site. An anonymous profile is created with an UUID.
In a mobile app, that customer created a profile with an email.
For some time, data and activity history is collected separately by the website and the app.
The customer provides the email in a form on the website (same email as in the app).
The Web SDK tries to update the profile (identified by the UUID from the browser) with new data (the email and other data from the form, if applicable).
In the database, there are two profiles that match the request - one identified by the UUID, the other by the email.
The system attempts to merge the profiles as described in this article.

What if clientId is one of the identifiers?

If you want to merge profiles by using clientId, you must use the dedicated endpoints.

Properties, tags, and attributes

Properties are the data stored outside of the attributes object of a profile’s data: clientId, email, phone, customId, uuid, firstName, lastName, displayName, company, address, city, province, zipCode, countryCode, birthDate, sex, avatarUrl, anonymous, agreements (object), tags (list)

Attributes are the data stored in the attributes object.
When non-unique emails are enabled, the profile’s email and marketing agreement are attributes!
To see the properties and attributes of a profile, fetch its data with /v4/clients.

When profiles are merged:

All properties (including tags) of the source profiles are ignored and lost.
If an attribute already exists in the target profile, it’s not modified. In this case, attribute values from the source profiles are lost.
If an attribute from a source profile doesn’t exist in the target profile, it’s copied into the target profile.

Important: If the merge was caused by an update request, the request is processed like a regular update after the merge is complete and can modify the properties, tags, and attributes of the target profile.

Identities and event history

UUIDs (including historical UUIDs) of the source profiles are added to the historical UUIDs of the target profile.
Thanks to this, events of source profiles become associated with the target profile.

Moving identities and events when merging

The identities (UUIDs) can be found on the profile’s card:

Location of the Identities list on a profile's card.

Allowed combinations

To prevent data loss, profiles from some groups cannot be merged into other groups. A recognized profile can never be a source when the target is anonymous.

If the merge would result in a merge that’s not allowed, the operation is cancelled. Profiles aren’t merged and data from the original update request is ignored.

Column: target Row: source	To: Anonymous	To: Has email, recognized	To: Has custom ID, anonymous	To: Has custom ID, recognized (non-unique emails enabled)
From: Anonymous
From: Has email, recognized				¹
From: Has custom ID, anonymous
From: Has custom ID, recognized

¹See Special case - email conflict

Special case - email conflict

This can happen only when non-unique emails are disabled.

If a profile A (is recognized, has email) is merged into a profile B (is recognized, has custom ID) that also has an email, the email from A is lost, because properties are not transferred from source profiles to the target profile.

Exception: If the update operation that caused the merge included the email from A as the identifier, the mail from A is retained. This is because the update operation is resumed after the merge, so the email from the update request (which is now treated as a regular update of B) is saved into the profile after the merge.