Merge contacts


Using the MergeContact pipeline to merge contacts and custom contact information.

When the xDB contains more than one contact record describing the same person, you can merge contact records. All the information stored in these contact records merge into one record. The old contact record is removed and replaced with a reference to the updated contact record, so that all future operations can access the updated and consolidated information.

If you create custom contact facets using the ContactEntity API or have implemented any other customizations on the contact then you need to overwrite the merging logic to ensure that the data for any custom facets is merged correctly. Custom contact facets may include data that you want to merge which is specific to your organization or solution.

To customize the merging logic, you need to add a new processor to the mergeContacts pipeline.

Sitecore invokes the merge pipeline when:

  • An unidentified contact is identified as a contact already known in the system. The contact records are merged, as part of the contact identification process.

  • The system has been operating without an xDB connection. For example, due to network or configuration problems. In this situation Sitecore will attempt to merge collected behavior and personal information into the primary contact record in xDB. Merging is used as a way of recovering from database or network issues.

The merge operation is performed on two contact records: source record and target record. After the merge operation has completed, the target record is updated in xDB with the new information, and the source record is obsoleted removing all information related to it from the xDB.

MergeContactArgs provides you with the following two properties to implement this:




A reference to the contact record that will be removed after the merge. This is the source of the contact information to be merged.


A reference to the contact record that will be kept in the xDB after the merge. This is the target of the contact information to be merged.

The merge pipeline contains a predefined set of processors that implement the default merge contact rules.

If you have created custom contact facets, you can also create custom processors using the MergeContact pipeline to merge your custom contact facets.

To create a custom merge:

  1. Create a class that is derived from the MergeContactProcessor class in the Sitecore.Analytics.Pipelines.MergeContacts namespace and override the void Process(MergeContactArgs args) method.

    namespace CustomCode
      using Sitecore.Analytics.Pipelines.MergeContacts;
      public class CustomMergeLogic : MergeContactProcessor
        public override void Process(MergeContactArgs args)
          // TODO: Use args.DyingContact and args.SurvivingContact
          // TODO: write into args.SurvivingContact
  2. In the void Process(MergeContactArgs args)method use the properties args.DyingContact and args.SurvivingContact to access the contact records that you want to merge.

  3. Assign the merged values to args.SurvivingContact. All the information in args.DyingContact will be lost after the merge.

  4. Add your custom processor to the mergeContacts pipeline. The processor in this example is called CustomCode.CustomMergeLogic.

            <processor type="CustomCode.CustomMergeLogic" />


The merge pipeline is invoked synchronously as part of each HTTP request. Therefore, any customizations that you add to the pipeline should avoid long running operations and requests to databases and third-party systems.