Duplicate Management
Duplicate Management is the Salesforce feature set that detects and prevents duplicate records across standard and custom objects through Matching Rules, Duplicate Rules, Duplicate Jobs, and a logging layer built on the DuplicateRecordSet object.
Definition
Duplicate Management is the Salesforce feature set that detects and prevents duplicate records across standard and custom objects through Matching Rules, Duplicate Rules, Duplicate Jobs, and a logging layer built on the DuplicateRecordSet object. Matching Rules define how the engine compares records, including fuzzy matching, edit distance, and exact field comparisons. Duplicate Rules wire matching rules to user actions and decide what happens when a duplicate is found: block the save, allow with an alert, or allow silently and log for later review. Duplicate Jobs run matching rules against existing data in batch, producing the same logs as real-time rules.
The feature is included in every Sales Cloud and Service Cloud edition above Group, and ships with prebuilt rules for Account, Contact, and Lead. Custom objects gain duplicate detection by creating a new Matching Rule and a corresponding Duplicate Rule. Cross-object matching is supported, so a Lead can be checked against existing Contacts and vice versa. The whole framework is configurable through Setup with no Apex required, and the audit logs are queryable through SOQL and reportable through the standard report builder.
How Salesforce''s duplicate detection actually works
Matching Rules: the comparison engine
A Matching Rule defines which fields are compared and how. Each field can use Exact, Fuzzy, or Edit Distance matching, with optional normalizations for company names, person names, emails, and addresses. The rule is the lowest-level building block of duplicate detection. Multiple Duplicate Rules can reference the same Matching Rule, and a Matching Rule can be cross-object, comparing Leads to Contacts for example. The standard Account, Contact, and Lead Matching Rules ship pre-built; custom objects need a Matching Rule created from scratch.
Duplicate Rules: the policy layer
A Duplicate Rule wires a Matching Rule to an action. For Create and Edit events separately, you choose Block, Allow with alert, or Allow with report. You can also bypass sharing rules for the duplicate check, which lets the engine see records the running user cannot. The rule is where you set conditions: who the rule applies to (everyone or a subset of profiles), what record types trigger it, and any field-level filters that scope the check.
Duplicate Jobs: the batch path
Duplicate Jobs run a Matching Rule against existing data in your org and write DuplicateRecordSet entries for every cluster they find. Jobs only apply to standard Account, Contact, and Lead, plus custom objects with an active Matching Rule. Run a job after every large data load to clean up duplicates the real-time rules missed, and run one annually as a baseline data-quality audit.
DuplicateRecordSet and the steward queue
Every duplicate detection event writes a DuplicateRecordSet row, plus one DuplicateRecordItem per member record. Data stewards work from the Duplicate Record Sets list view, merging or unlinking records cluster by cluster. The same backing data feeds the Lightning Potential Duplicates component on the record page, so end users see the same matches the steward queue does.
User experience on save
When a Duplicate Rule fires on Save, the user sees an alert listing matched records with their key fields. The alert includes a Save Anyway option for Allow with alert rules, or a hard block for Block rules. Lightning surfaces the alert inline; Classic shows it in a modal. The Manage Duplicates user permission lets specific users override Block actions; without it, the save fails and the user must edit the record to remove the conflict.
Cross-object matching for Lead-to-Contact
The most common cross-object scenario is Lead-to-Contact matching: a sales rep enters a Lead for someone who already exists as a Contact. A standard Matching Rule for this exists out of the box, and the Lead Duplicate Rule can use it alongside the Lead-to-Lead rule. The same applies to Lead-to-Account when matching by company name. Cross-object rules let you catch duplicates that single-object rules miss.
Limits and gotchas
Each object can have up to 5 active Duplicate Rules and 5 active Matching Rules. Matching Rules take up to several minutes to activate after creation. The platform queues activations and you cannot edit a rule while it is queued. Duplicate detection does not run on records created by Apex unless the calling code uses Allow Save with the Duplicate API, so any data migration code that uses Database.insert without options will bypass duplicate rules entirely.
Set up Duplicate Management on a new object
Setting up Duplicate Management for a new object means three things in order: define how records should be compared, decide what to do when a match is found, and build the steward workflow to triage logs. The standard Account, Contact, and Lead rules ship pre-configured, but custom objects need every step.
- Decide what makes a duplicate
Before opening Setup, list the fields that uniquely identify a record (Email, Phone + Account Name, Tax ID). Decide which require exact matches and which can tolerate fuzzy comparison.
- Create the Matching Rule
Setup > Matching Rules > New. Select the object, define match criteria field by field, set the matching method per field, and save. The rule takes a few minutes to activate.
- Create the Duplicate Rule
Setup > Duplicate Rules > New. Reference the Matching Rule, choose actions for Create and Edit (Block, Allow with alert, Allow with report), and define any user or record-type filters.
- Test in a sandbox
Insert known duplicates manually and via API to confirm the rule fires as expected. Test with Bypass Sharing Rules on and off; the behavior differs by user permission.
- Run a baseline Duplicate Job
Setup > Duplicate Jobs > New. Select the Matching Rule and run a one-time job against existing data. This builds the initial backlog of duplicates already in the org.
- Add the Potential Duplicates component
On the Lightning record page, drop the Potential Duplicates component on the right rail. End users will see matches on every record they open, which catches duplicates that the steward queue might miss.
- Build the steward queue
Pin the Duplicate Record Sets tab to the data-quality team's nav. Build a report joining DuplicateRecordSet to DuplicateRecordItem, scheduled weekly, grouped by rule and created date.
Save fails unless user has Manage Duplicates permission. Use for high-stakes objects like Accounts where a duplicate creates real downstream pain.
User sees the warning but can override. The middle-ground option, fits most B2B Contact and Lead use cases.
Saves silently and logs for later review. Use for high-volume inbound where stopping users would hurt conversion.
Matching Rule setting that lets the engine compare against records the running user cannot see. Required for cross-team dedup.
Match Leads to Contacts or Accounts. Catches duplicates that single-object rules miss.
- Apex insert() bypasses Duplicate Rules unless the code explicitly sets DMLOptions.DuplicateRuleHeader.allowSave. Any integration code written before this was understood is probably bypassing your rules silently.
- Each object caps at 5 active Duplicate Rules and 5 Matching Rules. Plan rule design tightly; overlapping rules create noise and confuse stewards.
- Matching Rule activation takes several minutes and queues other operations on the rule. Plan rule changes for low-traffic hours.
- Duplicate Jobs only run on Account, Contact, Lead, and custom objects with an active Matching Rule. They do not work for Opportunity, Case, or other standard objects.
- Bypass Sharing Rules can surface matches the user cannot then merge or view. Use it for steward profiles, not standard sales users.
Trust & references
Straight from the source - Salesforce's reference material on Duplicate Management.
- Things to Know About Duplicate RulesSalesforce Help
- Things to Know About Matching RulesSalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What does Duplicate Management include?
Q2. What actions can a Duplicate Rule take?
Q3. Why does duplicate management need to be ongoing?
Discussion
Loading discussion…