Merging User Profiles

As users interact with your mobile apps and websites and you create user profiles in Iterable, you may sometimes end up creating multiple Iterable user profiles for the same user. This might happen when you track an anonymous user with a placeholder ID who later signs in to a different Iterable user profile. Or, maybe separate parts of your own data infrastructure track the same user with different user IDs.

This article describes how to merge users with Iterable's API.

# In this article

# How it works

To combine two Iterable user profiles, you can use the merge users API.

POST /api/users/merge

This API does the following:

1. Accepts a source user identifier and a destination user identifier as parameters in the request body.

2. Merges the source user data into the destination user profile (including system events, custom events, and user profile fields).

3. Deletes the source user profile.

   In some cases, when the destination user doesn't yet exist, Iterable simply changes the identifier on the source user profile. This is common when an anonymous user converts to a known user and you want to create a known user profile for them.

# Merging data when the destination user already exists

When the specified destination user already exists in the Iterable project associated with the merge user API request:

• The existing destination user profile receives copies of the source profile's data, including system events, custom events, and user profile fields.

• User profile profile fields that exist on the source profile but not the destination profile are copied to the destination profile.

• User profile fields that exist on the destination profile but not the source profile remain on the destination profile.

• When there's a conflict (the same field exists on the source profile and destination profile), the destination profile field "wins." That is, the field in question remains on the destination profile, with its original value. The value on the source profile is lost.

• Objects are not combined in a merge operation.

• Arrays are not, by default, combined in a merge operation. However, you can tell the API to merge the data of specific arrays. For details, see Merging array data.

  Exception: The devices array is de-duplicated based on the devices.platformEndpoint field.

• Source devices are added to the merged devices array unless the destination already has an element in devices with the same platformEndpoint.

• The destination profile retains its subscription-related fields and their values: subscribedMessageTypeIds,unsubscribedMessageTypeIds, unsubscribedChannelIds. However, if the destination profile does not have these fields, they're copied from the source profile to the destination profile.

• After the destination profile receives copies of the source profile's data (as described above), the source profile is deleted.

# Merging data when the destination user does not yet exist

Sometimes, the destination user profile doesn't yet exist in the Iterable project associated with the merge user API request. This can happen when an anonymous user converts to a known user and you want to create a known user profile for them.

When the specified destination user does not yet exist in the Iterable project associated with the request:

• In userID-based projects, Iterable changes the source profile's userId to the specified destinationUserId.

• In hybrid projects, Iterable changes the source profile's email or userId to the specified destinationEmail or destinationUserId.

• In email-based projects:

  • For requests that identify a destination user by destinationUserId, Iterable changes the source user's userId to the specified destinationUserId.

  • For requests that identify a destination user by destinationEmail, Iterable creates a new user profile with the specified email. This new profile receives copies of the source profile's system events, custom events, and user profile fields. Then, the source profile is deleted.

# Important considerations

Merging user profiles is a powerful operation that can have significant implications for your Iterable project. Before you merge user profiles, consider the following:

# Merges process asynchronously

Merge operations take at least 5 minutes to process and occur asynchronously in the background. A successful API response indicates that the merge request has been accepted and is being processed, not that the merge has been completed.

# Source user is deleted

When Iterable received a successful call to the merge users endpoint, the following happens to the source user data:

• Source profile data is merged to the destination profile.

  When there are conflicts (the same same field exists on the source user and the destination user), Iterable keeps the data from the destination profile and the field value from source data is lost.

• The source profile and all its data are deleted.

Exceptions: In some cases, when the specified destination user does not yet exist, Iterable simply changes the identifier on the source profile to the specified destination identifier. For more information, see Merging data when the desination user does not yet exist.

# No GDPR forget

When the merge users endpoint deletes the source user, it does not GDPR forget that user.

# Unprocessed events

After a merge, Iterable associates already-submitted but not-yet-processed source-profile events with the destination profile. These events are not dropped.

# Journey users

If a source user happens to be in a journey at the time they're merged with another user:

• That source user still continues on the journey — even after Iterable shows their profile as deleted (when the API no longer returns their user profile).
• A journey's interactions with the deleted source user are applied to the
  destination user (for example, user profile updates).
• Message sends triggered by the profile of the deleted source user are sent to the destination user.

# Journey lifetime entrances

After a user merge, the destination user's lifetime journey entrance counts are not updated to include journey entrances from the source user. This means that, after a merge, it's possible that a merged user's lifetime journey entrance count may be higher than the journey's maximum allowable number of lifetime entrances.

In other words, post-merge, (source user entrances) + (destination user entrances) may be greater than the lifetime maximum entrances for that journey, but the source user's entrances aren't counted on the destination user's profile.

# Brand Affinity and Predictive Goals

During a user merge, if the destination user has an itblDS object (which stores information about Brand Affinity™ and Predictive Goals), its value is retained (since, in cases of field conflict, the destination profile "wins"). However, the values found in this object may be outdated until their next recalculation if the destination user profile contained additional pertinent data.

On the other hand, if the source user has an itblDS object but the destination user does not, the source object is copied to the destination user.