Skip to main content

Auto-merge of External Contacts overview

Genesys Cloud automatically merges the duplicate external contacts in the background every 24 hours based on certain key identifiers of a contact and streamlines identity resolution of contacts. In Genesys Cloud, the identity resolution algorithm matches the incoming interaction to an existing contact using available real-time identifiers such as phone number, email address, external ID, and so on. When customers choose multiple channels to reach the contact center, for example, phone, email, or chat, each new identifier is resolved against existing records at the time of that interaction. Identifiers added partway through a conversation, or in a later interaction, aren’t automatically applied back to older, separate contact records for the same person. Over time, this can result in multiple contact records for the same customer instead of one.

The auto-merge contacts feature merges multiple external contact records of the same contact into a single record based on certain merging rules. During auto-merging, Genesys Cloud scans your organization’s external contacts, identifies records sharing identical normalized identifiers such as the same phone number or email address, and automatically merges duplicate contacts into a single record. Auto-merging complements real-time identity resolution by cleaning up duplicates that accumulate over time between interactions. Existing manual merge capabilities within external contacts remain unchanged.

Key characteristics of background automatic merging

  • Exact matching: Merging relies strictly on exact matches across normalized identifiers. No fuzzy or partial matching is performed.
  • Turned-off by default: Automatic merging requires explicit admin activation at the organization level.
  • Scan transparency: The scan history table logs duplicate clusters daily regardless of whether merging is enabled, allowing administrators to evaluate potential impact before activation.
  • Notification banner: When duplicates exist and auto-merge is off, an informational banner appears on the External Contacts and Organizations page. Banner information states, “There are [count] duplicate contact groups identified within your directory. Enable auto-merge on Identity Resolution to resolve duplicates.” The banner is visible only to users with permission to view external contacts, and the count reflects the Total Clusters value from the most recent scan. To enable auto-merge, see .
  • Irreversible action: Automatic merges cannot be undone within the product interface.

Merging rules

Auto-merging uses the normalized identifiers to identify duplicate contacts and applies the following rules while merging contacts:

  • Phone numbers: Must resolve to E.164 format. Unresolvable numbers are excluded from duplicate detection. Phone numbers with different extensions are treated as distinct.
  • WhatsApp identifiers: Normalized to E.164 format and matched against regular phone numbers. A WhatsApp number and a phone number that resolve to the same E.164 value matches each other.
  • Email addresses: Case-in-sensitive comparison (converted to lowercase for comparison).
  • External ID: Matched as a combined pair of External ID and External Source.
  • Facebook ID, Instagram ID, and X (Twitter) ID: Matched on the numeric or opaque ID only, not on the display handle.
  • Apple ID: Matched on the unique platform identifier.

Operational guardrails

To prevent unintended data consolidation, the auto-merge process enforces the following restrictions:

  • Division and organization boundary: Contacts are only merged within the same division and organization. Cross-division and cross-organization contacts are not merged.
  • Cluster size limits: A duplicate group is called a cluster and it must contain contacts anywhere between 2 and 10. Clusters exceeding 10 contacts such as shared corporate phone numbers are excluded to prevent unsafe bulk merging.
  • Custom contact types: Contacts with differing custom contact types are not merged. If a cluster contains multiple custom types, the cluster is divided by contact type and merged as independent subgroups. Contacts without a custom type can merge with contacts assigned to a custom type.
  • No automatic rollback: Merges cannot be undone automatically. Genesys recommends keeping the auto-merge feature turned-off for several days and monitor the scan results. After you’re confident with the scan results, enable auto-merge.