Overview

This article explains how Reltio Automatic Merge by Crosswalks works, why duplicate relationships may appear after a merge, how to identify the crosswalk responsible for a merge, and how to remediate or prevent similar situations.

Symptoms

Customers may observe one or more of the following:

• Two previously separate entities are automatically merged.
• Duplicate relationships (for example, multiple HOUSEHOLD or PERSON EXT relationships) appear on the surviving profile.
• The merge history shows an "Automatic Merge by Crosswalks" event.
• The crosswalk value that triggered the merge is not visible on the surviving entity before the merge event.
• Users suspect a ReltioCleanser crosswalk or Full Name cleansing process caused the merge.

Cause

Reltio enforces crosswalk uniqueness across entities. When two entities receive the same crosswalk value, the platform treats them as representing the same source record and automatically merges them.

In the investigated case, the merge was triggered by the following crosswalk:

PL_Homesite_Digital = 999999|JOHNSON|1990|PNI|4

The merge occurred as a Merge by Crosswalks event.

Why the Crosswalk May Not Appear on the Survivor Before the Merge

A common point of confusion is that the triggering crosswalk may not appear in the surviving entity's history prior to the merge.

This occurs because:

1. The triggering crosswalk exists on the incoming (contributor/loser) entity.
2. Reltio performs an automatic merge when the duplicate crosswalk is detected.
3. During the merge, crosswalks from the contributor entity are transferred to the survivor entity.
4. After the merge completes, the crosswalk becomes visible on the survivor profile.

As a result, users may not see the triggering crosswalk on the survivor profile immediately before the merge event.

Why Duplicate Relationships Appear

When entities are merged, Reltio aggregates data from all contributing entities, including:

• Crosswalks
• Attribute values
• Relationships
• Interactions

If both entities contain relationships of the same type, those relationships are carried forward to the surviving entity. This can result in duplicate HOUSEHOLD, PERSON EXT, or other relationship records that may require review after the merge.

Confirming Which Crosswalk Triggered the Merge

Use the Crosswalk Tree API to review merge details:

GET /reltio/api/{tenantId}/entities/{entityId}/_crosswalkTree

The response contains:

• Merge timestamp
• Merge reason
• Winner and contributor entities
• Crosswalk information
• Merge contributors
• Merge crosswalk details

This API is the recommended method for identifying the exact crosswalk responsible for an automatic merge.

Remediation: Unmerge the Contributor Entity

If the merge was incorrect and the contributor should exist as a separate profile, perform an unmerge using the contributor URI.

Example:

POST /reltio/api/{tenantId}/entities/{survivorEntityId}/_unmerge?contributorURI=entities/{contributorEntityId}

Important:

• Unmerge is performed by contributor entity.
• Unmerge cannot be performed against an individual crosswalk value.
• The contributor profile is restored as a standalone entity.

Recommended Validation Before Unmerge

Before performing an unmerge, capture the current state of the survivor entity:

GET /reltio/api/{tenantId}/entities/{entityId}
GET /reltio/api/{tenantId}/entities/{entityId}/_crosswalkTree
GET /reltio/api/{tenantId}/entities/{entityId}/_relations

Review relationship data after the unmerge to ensure HOUSEHOLD, PERSON EXT, and other relationships are restored as expected.

Prevention

To prevent future automatic merges:

1. Review the logic used to generate source crosswalk values.
2. Ensure each crosswalk uniquely identifies a single source record.
3. Include additional source-specific identifiers when necessary, such as:
   • Source Person ID
   • Source Table Identifier
   • Person Sequence Number
   • Other source-system unique keys

Important

Automatic crosswalk merging cannot be disabled. Reltio relies on crosswalk uniqueness to maintain source-record identity and data integrity.

Key Takeaways

• Automatic merges occur when duplicate crosswalk values exist across entities.
• The triggering crosswalk may originate from the contributor entity and only appear on the survivor after the merge.
• Duplicate relationships are an expected consequence of entity aggregation during merge.
• The _crosswalkTree API is the primary tool for investigating merge causes.
• Incorrect merges can be reversed through contributor-level unmerge operations.
• Properly designed unique crosswalk values are the best prevention strategy.