Implementing Deterministic Customer Identity Matching Using Phone, Email, and Account Keys

How-To-Articles
1

Implementing Deterministic Customer Identity Matching Using Phone, Email, and Account Keys

What This Guide Covers

You will configure a deterministic identity resolution strategy within Genesys Cloud CX to correlate inbound interactions across voice, digital, and CRM channels using phone number, email address, and external account identifiers. The end result is a unified customer context that persists across sessions, enabling accurate routing, personalized scripting, and compliant data handling without relying on probabilistic heuristics.

Prerequisites, Roles & Licensing

  • Licensing: Genesys Cloud CX 2 or CX 3 license is required to access the Customer Data Platform (CDP) or Unified Data Model (UDM) features. CX 1 licenses do not support advanced identity resolution.
  • Permissions:
    • Data > Customer Data Platform > Edit
    • Administration > Organizations > Edit
    • Integration > CRM > Edit (for Salesforce, Microsoft Dynamics, or custom REST integrations)
    • Security > OAuth Client > Edit (if using custom API integrations for identity enrichment)
  • External Dependencies:
    • A configured CRM integration (Salesforce, Microsoft Dynamics, or a custom REST endpoint) that exposes a unique AccountID or CustomerID.
    • A defined data schema in the CDP that includes fields for phone_number, email_address, and account_id.
    • Access to the Architect flow designer to map identity attributes into the interaction context.

The Implementation Deep-Dive

1. Define the Identity Resolution Strategy in CDP

The core of deterministic matching lies in how the platform resolves multiple data points into a single customer profile. Genesys Cloud uses the Customer Data Platform (CDP) to store and resolve these identities. You must explicitly define which attributes serve as the primary keys for matching.

Configuration Steps

  1. Navigate to Data > Customer Data Platform.
  2. Select Identity Resolution.
  3. Create a new Resolution Strategy named Deterministic_Phone_Email_Account.
  4. Add the following Identity Attributes with the specified matching rules:
    • Attribute: phone_number
      • Type: Primary Key
      • Normalization Rule: E164 (Strip all non-numeric characters, prepend country code if missing)
    • Attribute: email_address
      • Type: Primary Key
      • Normalization Rule: Lowercase (Convert to lowercase, trim whitespace)
    • Attribute: account_id
      • Type: Secondary Key (High Confidence)
      • Normalization Rule: None (Exact match)

Architectural Reasoning

We designate phone_number and email_address as Primary Keys because they are universally available across voice and digital channels. account_id is designated as a Secondary Key with high confidence because it is often only available after the customer has authenticated or when the interaction originates from a CRM-triggered outbound campaign. By using a deterministic strategy, we avoid the latency and false-positive risks associated with fuzzy matching or probabilistic scoring. The system will merge profiles if any primary key matches, ensuring that a customer calling from a mobile number and emailing from a desktop is recognized as the same entity.

The Trap: Ignoring Data Normalization

The most common misconfiguration is failing to enforce strict normalization rules. If you ingest phone numbers from a CRM in 1-800-555-0199 format and from an IVR in +18005550199 format, the system will treat them as distinct identities. This creates duplicate profiles, fragmenting the customer history. Always apply E164 normalization for phone numbers and Lowercase trimming for emails at the ingestion layer, not just at the display layer.

2. Ingest and Map Identity Data from External Systems

Deterministic matching requires that the external system (CRM) and the contact center platform share a common language. You must map the external AccountID to the Genesys CDP account_id attribute during every inbound or outbound interaction.

Configuration Steps for Salesforce Integration

  1. Navigate to Integrations > CRM > Salesforce.
  2. Ensure the Contact and Account objects are enabled for synchronization.
  3. In the Field Mapping tab, map the following:
    • Salesforce Contact.Email → Genesys email_address
    • Salesforce Contact.Phone → Genesys phone_number
    • Salesforce Account.Id → Genesys account_id

Configuration Steps for Custom REST Integration

If you are using a custom middleware (e.g., MuleSoft, Boomi, or a Node.js service), you must push identity data to the Genesys CDP via the Customer Data API.

API Endpoint:
POST /api/v2/customer-data-platform/identities

OAuth Scope: customer-data-platform:write

JSON Payload:

{
  "identities": [
    {
      "key": "phone_number",
      "value": "+14155552671",
      "type": "primary"
    },
    {
      "key": "email_address",
      "value": "john.doe@example.com",
      "type": "primary"
    },
    {
      "key": "account_id",
      "value": "ACCT-98765",
      "type": "secondary"
    }
  ],
  "attributes": {
    "tier": "Platinum",
    "last_order_date": "2023-10-15T14:30:00Z"
  }
}

Architectural Reasoning

Pushing identity data via API allows for real-time enrichment. When an agent opens a case, the middleware can query the CRM for the AccountID and immediately update the Genesys CDP profile. This ensures that the account_id is present in the context before the interaction is routed, enabling skills-based routing based on account tier or product ownership.

The Trap: Asynchronous Data Latency

A frequent error is assuming the CDP update is instantaneous. The CDP API is eventually consistent. If you route an agent to a skill based on account_id immediately after the API call, the profile may not yet be enriched. To mitigate this, implement a retry mechanism in your middleware or use a synchronous lookup in the Architect flow (via the Get Customer Profile block) after the initial identity push to confirm the data is present. If the profile is not found, fall back to a default queue or prompt the agent to manually search.

3. Configure Architect Flows for Identity Enrichment

The Architect flow must capture identity data at the earliest possible point and enrich the interaction context. This ensures that downstream blocks (routing, scripting, CRM updates) have access to the resolved customer profile.

Configuration Steps

  1. Open the Architect flow designer.
  2. Add an Get Customer Profile block.
    • Input: Set the search_keys to include phone_number (from the IVR) or email_address (from digital channels).
    • Output: Map the result to a variable customer_profile.
  3. Add a Decision block to check if customer_profile is null.
    • True (Profile Found): Proceed to the Enrich Context block.
    • False (Profile Not Found): Proceed to a Collect Information block to gather missing identity data (e.g., ask for email or account number).
  4. Add an Update Customer Profile block if new identity data was collected.
    • Action: Merge
    • Data: Pass the newly collected email_address or account_id to the CDP.

Architectural Reasoning

We use the Merge action instead of Create to ensure that if a profile already exists (e.g., from a previous voice interaction), the new email address is linked to it rather than creating a duplicate. This is critical for maintaining a single view of the customer. The Get Customer Profile block acts as the single source of truth, resolving the identity using the strategy defined in Step 1.

The Trap: Over-Reliance on IVR Input

Many architects assume that the IVR will always capture the correct phone number. However, spoofed caller ID (CNAM) or incorrect trunk configurations can lead to mismatched phone_number values. Always validate the phone_number against the CDP. If the profile is not found, do not assume the customer is new. Instead, prompt for a secondary identifier (email or account ID) to confirm identity. This prevents the creation of “ghost” profiles for existing customers.

4. Implement Routing and Personalization Based on Resolved Identity

Once the identity is resolved, you can leverage the enriched account_id and email_address for advanced routing and personalization.

Configuration Steps

  1. In the Architect flow, add a Route to Queue block.
  2. Set the Routing Strategy to Skills-Based.
  3. Map the following skills based on the customer_profile:
    • If customer_profile.attributes.tier == "Platinum": Assign skill Premium_Support.
    • If customer_profile.attributes.last_order_date is within 7 days: Assign skill Post_Purchase_Support.
  4. Add a Set Variable block to pass the account_id to the agent desktop.
    • Variable: interaction.account_id
    • Value: customer_profile.identities.account_id

Architectural Reasoning

Routing based on resolved identity ensures that high-value customers or those with recent transactions are prioritized. By passing the account_id to the agent desktop, you enable screen pops in the CRM. The agent sees the customer’s history, open cases, and account details without manual lookup, reducing handle time and improving customer satisfaction.

The Trap: Skill Gaps

If you route based on account_id attributes that are not consistently populated in the CRM, you may create skill gaps. For example, if tier is null for 20% of customers, those interactions will fail to route to the Premium_Support queue. Always implement a fallback skill (e.g., General_Support) for cases where identity attributes are incomplete.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Duplicate Profiles Due to Unnormalized Data

The Failure Condition:
Two separate profiles exist for the same customer: one with phone_number: "1-800-555-0199" and another with phone_number: "+18005550199". The customer calls, and the system creates a new profile instead of merging with the existing one.

The Root Cause:
The normalization rule in the CDP Identity Resolution strategy was not set to E164, or the external system is sending inconsistent formats.

The Solution:

  1. Verify the normalization rule in Data > Customer Data Platform > Identity Resolution.
  2. Implement a data cleanup script using the Customer Data API to merge duplicate profiles.
    • API Endpoint: POST /api/v2/customer-data-platform/identities/merge
    • Payload: Include the source_profile_id and target_profile_id.
  3. Enforce E164 formatting in all external integrations (CRM, IVR, Digital Channels) before data is pushed to Genesys.

Edge Case 2: Identity Resolution Timeout

The Failure Condition:
The Get Customer Profile block in Architect times out, causing the flow to drop the call or route to a default queue.

The Root Cause:
The CDP is under heavy load, or the identity resolution strategy is too complex (e.g., using probabilistic matching with large datasets).

The Solution:

  1. Increase the timeout threshold for the Get Customer Profile block in Architect (default is 5 seconds, increase to 10 seconds if necessary).
  2. Simplify the identity resolution strategy by removing low-confidence secondary keys.
  3. Implement a caching layer in your middleware to store recent identity lookups, reducing the load on the CDP API.

Edge Case 3: GDPR/CCPA Data Deletion Requests

The Failure Condition:
A customer requests data deletion, but the profile persists because the account_id is still linked to other interactions.

The Root Cause:
The deletion request only removed the profile from the CRM, not from the Genesys CDP. The CDP retains interaction history and identity links even if the source system deletes the record.

The Solution:

  1. Use the Customer Data API to explicitly delete the profile from the CDP.
    • API Endpoint: DELETE /api/v2/customer-data-platform/identities/{profile_id}
  2. Ensure your data retention policy in Administration > Data Retention is configured to automatically purge old profiles.
  3. Implement a webhook from your CRM to trigger CDP deletion when a customer opts out.

Official References