Profile identity resolution and merging

Identity resolution determines when multiple profiles represent the same person based on shared information, such as an email address or member ID. When matching profiles are detected, the system automatically merges them into a single unified profile, consolidating all related data and activities.

Default identity resolution behavior

By default, the system merges profiles when they have a matching email address in the linked member entity, representing a registered user on a website. Profiles without an associated registered member are never merged by default.

You can configure identity resolution rules to match individual project requirements in the Customer data management application.

Configure identity resolution rules

Each identity resolution rule defines a piece of identifying information, called an identity, that the system uses to match profiles. Each identity is based on a specific field of a profile-related entity (contact, member, customer). When the value of an identity field is the same across two profiles, the system considers them to represent the same person and triggers a merge.

You can view and adjust the project’s identity resolution rules in the Customer data management application.

To add a new identity:

1. Select New identity resolution.
2. Fill in the rule properties:

   • Identity name

   • Source class – the Xperience class representing one of the entities connected to profiles. A database column from the given class can be selected as the identity.

   • Database column – the specific column from the selected Source class that holds the identity value. The system merged profiles when they have matching values in the identity column (if there are not conflicts in other immutable identity columns).

     Contact field limitations

     Column from the Contact class that are used in form field mapping cannot be set as an identity. Profile identities cannot accept values from unverified sources such as public forms.

   • Identity value mutability – determines if the value of the identity column can change when profiles are merged. See How profile merging works for more information.

3. Create the rule.

The new identity is added to the end of the list of current identities, with the lowest priority. You can add any required number of identities and reorder them as required.

Identity resolution rule ordering

When the system evaluates identity resolution rules to find matching profiles, the identities are processed in order of their Priority, from the lowest number (Priority 1 placed at the top of the list) to the highest.

To change the order of rules:

1. Open the Customer data management application.
2. Move identities up or down using the drag handle () to reorder them.
3. Select Save priorities to persist the new order.

How profile merging works

Profile merging is triggered when:

• A contact field is updated (for example, a visitor submits a form with their email address).
• A member is linked to a profile during registration.
• A member signs in – if you call IProfileSignInService.TryConnectMemberWithProfile during the member sign-in flow (see Connect members with profiles on sign-in).

When attempting to merge profiles, the system evaluates the configured identity resolution rules in order of their priority. The system goes through the following steps for each identity rule:

1. Retrieves the identity value for the profile that triggered the merge.
2. Searches for other profiles that share the same identity value.
3. When a match is found, the profiles are merged unless there is a conflict in another identity that is immutable.

For example, if two profiles are merged based on a match in identity A with Priority 1, but identity B with Priority 2 is immutable and the values are different, the merge does not occur (empty values are not considered as a conflict). If identity B is mutable, the profiles are merged and the value in the identity B column is taken from the profile that was updated to trigger the merge.

Connect members with profiles on sign-in

People can access your website using different devices and the profile may not always be tracked in the browser session. On sites with registration and authentication functionality, developers can connect the current profile with the member account and trigger the profile merging process.

This allows you to merge profiles created during new connections with the member’s existing profile that already contains data and logged activities from previous interactions.

To connect the current member with the current profile:

1. Edit your project’s sign-in logic, for example a sign-in controller).
2. Get an instance of the IProfileSignInService interface (available in the Kentico.CustomerDataPlatform.Web.Mvc namespace).
3. Call the IProfileSignInService.TryConnectMemberWithProfile method.

using Kentico.CustomerDataPlatform.Web.Mvc;

public class SignInController(IProfileSignInService profileSignInService) : Controller
{
    [HttpPost]
    public async Task<IActionResult> SignIn(SignInViewModel model, CancellationToken cancellationToken)
    {
        // ... Sign-in logic

        // Connects the signed-in member with the current visitor profile
        // Also triggers profile merging based on identity resolution rules
        await profileSignInService.TryConnectMemberWithProfile(cancellationToken);

        return RedirectToAction("Index", "Home");
    }
}

The method:

• Gets the currently signed-in member from the HTTP context.
• Gets the current visitor profile.
• Links the member to the profile.
• Triggers the profile merging process based on the configured identity resolution rules.

The method returns true if the member was successfully connected. Returns false if the connection was not made.