A CRM Duplicate-Prevention Playbook for Integrations

Preventing duplicate CRM records requires two different decisions. First, decide whether an incoming event has already been processed. Second, decide whether the person or organization it describes already has a record. A retry of the same event and a new inquiry from an existing customer are different cases. Treating both as “match the email” can create duplicate tasks, attach data to the wrong person, or merge records the client wanted separate.

This playbook gives a consultancy a way to specify matching, retry, and review behavior before connecting systems. The client must approve identity policy and merge authority. The implementer must verify what identifiers, lookup methods, and update operations are actually available in the client's systems. The examples below are illustrative and do not assume any particular CRM feature.

Inventory identifiers and their limits

List the identifiers carried from each source to the CRM. A source record ID may remain stable when an email address changes. A transaction or submission ID may identify one event but not the person. An email address can be shared, changed, mistyped, or absent. A phone number can be reused or belong to a household. Do not call any field unique until its behavior in the client's data is checked.

Build a mapping table with the source system, record type, source ID, CRM object, CRM lookup field, and whether the field can change. Add the rule for when the ID is missing. If two systems refer to the same customer, record how the cross-system link is established and maintained. Where the link is uncertain, keep the candidate in review rather than manufacturing a permanent association.

Agree which fields are safe to update after a match. Matching a contact does not automatically mean the source may overwrite owner, lifecycle stage, consent preference, or account association. Write the field-level source of truth alongside the identity rule. That keeps a successful lookup from silently becoming an unauthorized data change.

Separate replay protection from identity matching

A replay key identifies the operation already attempted, such as a source event ID combined with its source name. Before creating anything, the integration checks whether that event has a recorded outcome. If it does, return or inspect that outcome rather than creating a second record or sending a second message. If the source provides no stable event ID, document the weaker key or require a review step. Do not promise exact-once processing when the tools do not support it.

Identity matching answers a separate question: which CRM record, if any, represents the subject? A first pass might use a stable source ID already linked to a CRM record. A second pass may consider an exact email match, but only under the client's approved policy. Name and company similarity can produce candidates for review; it should not silently authorize a merge. The same incoming record can be a new event for an existing contact, so a replay check cannot replace the identity check.

Write the two decisions as a matrix:

Event status	Identity status	Safe default to review
Already processed	Any	Inspect recorded outcome; do not repeat side effects
New event	One verified linked record	Apply approved field updates to that record
New event	No match	Create only if required fields and policy allow it
New event	Several possible matches	Hold for human review without merging

The table is a starting point. In a real design, specify how the system records the outcome and what happens if it crashes between creating a record and saving the replay marker. A retry after that partial success must look for the created record before another create. If the available connector cannot do this safely, use a manual recovery procedure and state the residual risk.

Define collision and merge authority

Two exact identifiers can disagree. An email may point to one contact while a source ID points to another. Do not pick whichever lookup returned first. Preserve both references, stop the automatic update, and send the case to an owner who can inspect the source records. The review item should explain the conflict without copying more personal data than needed.

Merging is a separate action from preventing a new duplicate. A merge can change associations, ownership, history, reporting, and downstream integrations. Decide who may approve it, which system owns the final identity, and how to record the decision. If a platform does not support a safe reversal, say so in the procedure. A low duplicate count is not a quality metric if the workflow achieves it by combining distinct people.

When a human resolves a collision, update the cross-system mapping and record why the decision was made. Otherwise the same pair may return to the review queue on the next event. Test whether an existing open task, opportunity, or account relationship survives the resolution as expected.

Test the cases that break simple rules

Use approved test records in the relevant environment. At minimum, test one new person, one known person with a stable source ID, a changed email, two people sharing a phone number, two similar names, and an event replay. Then test a timeout after the CRM write but before the integration records success. The expected result should describe records, associations, tasks, notifications, and any review item, not just the API response.

For each case, capture input identifiers, expected lookup result, expected action, actual result, and evidence location. Run a second pass after correcting a defect to check that the fix does not break the ordinary path. If a test cannot be performed because the connector hides a retry or the sandbox differs from production, record that limitation and define a controlled observation plan for the first live events.

A useful acceptance statement is concrete: “Replaying source event X does not create another contact or task, and the event history points to the original CRM record.” Another is: “Conflicting identity keys create a review item and do not overwrite either contact.” These statements can be checked by the client operator. “No duplicates ever” cannot.

Handoff and ongoing review

The handoff should contain the identifier map, replay key, lookup order, field ownership, collision rule, review owner, merge authority, test results, and recovery steps for partial writes. Ask the operator to walk through a known match and an ambiguous candidate using only the notes. If they cannot tell when to retry, pause, or escalate, the process is not yet operable.

After release, inspect duplicate creation, unresolved candidates, false matches, and corrections by source path. Review examples alongside counts. A drop in created duplicates could mean better matching, fewer inbound records, or over-aggressive merging. Document which interpretation the evidence supports before changing thresholds. Keep the review cadence and ownership within the client's agreed operating model.

The CRM data-mapping specification helps define field ownership, while the Salesforce integration QA guide gives a broader test frame. Syncraft offers scoped CRM and RevOps implementation support and a sample-data workflow design for discussing a proposed flow before live accounts or records are involved.