Duplicate Rule
A Duplicate Rule is the Salesforce configuration that tells the platform what to do when a user or an API call attempts to create or edit a record that matches an existing one.
Definition
A Duplicate Rule is the Salesforce configuration that tells the platform what to do when a user or an API call attempts to create or edit a record that matches an existing one. Each Duplicate Rule references a Matching Rule (which defines the comparison logic) and specifies separate actions for Create and Edit events: Block the save, Allow with alert, or Allow with report. The rule also defines who it applies to, which record types trigger it, and any field-level filter conditions that scope the check.
Duplicate Rules sit between Matching Rules and end-user actions. The Matching Rule decides whether two records are similar enough to count as duplicates; the Duplicate Rule decides what happens next. Out of the box, Salesforce ships Duplicate Rules for Account, Contact, and Lead, including cross-object rules that compare Leads to Contacts. Custom objects need a new rule created from scratch. Up to 5 Duplicate Rules can be active per object simultaneously, with rules evaluated in the order shown in Setup.
How a Duplicate Rule decides what to do
The three action options on Create and Edit
Each Duplicate Rule has separate action settings for Create (when a record is being inserted) and Edit (when a record is being updated). Each can be set to Block, Allow with alert, or Allow with report. Block fails the save unless the user has Manage Duplicates permission. Allow with alert shows a warning the user can override. Allow with report saves silently and writes the match to the DuplicateRecordSet log for later review. Most B2B orgs run Create on Allow with alert and Edit on Allow with report, because edits rarely create new duplicates.
The Bypass Sharing Rules toggle
On the Matching Rule referenced by the Duplicate Rule, you can enable Bypass Sharing Rules. With this on, the comparison engine sees records the running user cannot, so duplicate detection works across territory boundaries, role hierarchies, and private sharing models. Use it for steward roles; do not use it for standard sales users because the user will be told a duplicate exists but cannot see or merge it.
Conditional filters on the rule
The Conditions section of the Duplicate Rule lets you scope when the rule fires. Filter by user profile (only enforce for inside sales reps), by record type (only enforce for B2B Account record types), or by field values (only enforce when Country = US). Conditional filters are the cleanest way to handle the inevitable exceptions, like a marketing operations team that needs to bulk-insert known duplicates as test data.
Rule evaluation order
When multiple Duplicate Rules apply to the same record, they evaluate in the order shown in Setup, but all rules that match are evaluated. The user sees alerts for every rule that fires, and the Block action wins if any rule is set to Block. There is no early-exit semantic. Plan rule design to minimize overlap rather than relying on order.
Apex DML and the bypass
Apex inserts and updates do not enforce Duplicate Rules unless the code explicitly opts in via Database.DMLOptions.DuplicateRuleHeader.allowSave = false. Plain insert() and update() calls bypass duplicate detection entirely. This is the single largest cause of duplicate rules failing to prevent duplicates: an integration written before this nuance was understood loads records that should have been blocked. Audit every Apex insert path; ideally wrap them in a utility that sets DMLOptions consistently.
User experience on Block
When a Block rule fires, the user sees a Duplicate Records modal listing the matched records with their key fields. The Save button is disabled unless the user has Manage Duplicates permission, in which case a Save Anyway button appears. The modal shows record links the user can click to navigate to the existing duplicate, which is the right user experience: instead of creating a new Lead, the rep updates the existing one.
Cross-object rules in practice
The most useful cross-object rule is Lead-to-Contact: when a rep enters a new Lead for someone already in your CRM as a Contact. The standard Matching Rule for this exists out of the box, and the Lead Duplicate Rule can reference it alongside the standard Lead-to-Lead rule. The result: when the rep saves the Lead, they see both Lead duplicates and Contact duplicates in the same modal, with the option to convert the Lead and merge it with the existing Contact.
Create and activate a Duplicate Rule
Setting up a Duplicate Rule for a new object is a five-minute job in Setup, but the design decisions before and after take longer. Below is the full sequence: from matching logic to steward training.
- Confirm the Matching Rule exists
Duplicate Rules require a Matching Rule on the same object. Setup > Matching Rules. If none exists, create one and wait for it to activate before continuing.
- Navigate to Duplicate Rules
Setup > Duplicate Rules > New Rule. Select the object you want to apply the rule to. Each object can have up to 5 active rules.
- Reference the Matching Rule
On the Matching Rules section, select the Matching Rule that defines how records are compared. You can reference the same Matching Rule from multiple Duplicate Rules if you need different actions for different scenarios.
- Set actions for Create and Edit
Under Actions, choose the duplicate action for the Create event and the Edit event separately. The combination of Allow with alert on Create and Allow with report on Edit is the most common starting point.
- Add conditions if needed
Under Conditions, add filters to scope when the rule fires. Filter by profile, record type, or field values. Use this to handle exceptions cleanly rather than disabling the rule.
- Activate the rule
Save the rule, then activate it. Activation takes a few minutes. Test by attempting to insert a duplicate manually, and again through an API call, to confirm both paths enforce.
- Build the steward workflow
Pin the Duplicate Record Sets tab. Build a report on DuplicateRecordSet grouped by rule, scheduled to the data-quality team weekly. The rule without a steward workflow produces noise without action.
Save fails unless user has Manage Duplicates permission. Use for objects where duplicates create real downstream pain (Account, Tax IDs).
User sees the warning and can save anyway. The middle-ground option for most use cases.
Saves silently, logs to DuplicateRecordSet. Use when end-user friction is unacceptable but the steward queue is staffed.
Field-level filter that scopes when the rule fires. Filter by profile to exempt marketing ops; filter by record type to scope to B2B accounts only.
Each object caps at 5 active rules. Deactivate retired rules before adding new ones; you cannot exceed the cap.
- Apex DML bypasses Duplicate Rules unless code explicitly sets DMLOptions. Every integration written before this was widely known is probably bypassing the rule silently.
- All matching rules fire, not the first one. If you set up multiple rules expecting only one to apply, you will see multiple alerts on a single save.
- The Block action requires Manage Duplicates permission to override. Bulk imports run by users without this permission fail silently on duplicates and the import looks partial.
- Activating a Duplicate Rule queues other rule operations. Plan rule changes for off-peak hours; mid-day changes can leave users hitting validation errors during the activation window.
- Cross-object rules need a Matching Rule that supports cross-object comparison. The standard Lead-to-Contact rule does; custom-object cross-object rules require a custom Matching Rule built for the comparison.
Trust & references
Straight from the source - Salesforce's reference material on Duplicate Rule.
- Things to Know About Duplicate 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 a Duplicate Rule do?
Q2. What action modes do Duplicate Rules support?
Q3. When is Block the right action?
Discussion
Loading discussion…