Salesforce duplicate rules: complete setup, configuration, and management guide

Salesforce Duplicate Rules are the native tool for preventing duplicate records from being created in your org. They sound simple — define what a duplicate looks like, tell Salesforce what to do when it finds one. In practice, configuration choices have downstream consequences that most admins discover too late.

This guide covers how Matching Rules and Duplicate Rules work together, step-by-step setup, Apex-level enforcement for developers, Duplicate Jobs for existing data, where native tools reach their limits, and a configuration checklist you can use today.

Matching Rules vs. Duplicate Rules: the core distinction

Salesforce duplicate management uses two separate components. Confusing them is the most common configuration mistake.

Matching Rules define how Salesforce identifies potential duplicates. They specify:

• Which object to scan (Account, Contact, Lead)
• Which fields to compare (Name, Phone, Email, Address)
• Which matching method to use (Exact or Fuzzy)

Duplicate Rules define what happens when a Matching Rule finds a potential duplicate. They specify:

• Which Matching Rules to reference- What action to take (Alert, Block, or Report)
• Whether the rule applies to UI, API, or both- Which record types to include

Think of it this way: Matching Rules are the detection engine. Duplicate Rules are the response policy. You need both — a Matching Rule without a Duplicate Rule detects duplicates silently. A Duplicate Rule without a Matching Rule has nothing to reference.

Standard out-of-the-box rules

Salesforce provides standard Matching Rules (inactive by default). To use them:

Standard Account Matching Rule

• Fields Account Name, Billing Street, Billing City, Billing State, Billing Postal Code
• Method: Fuzzy on Account Name, Exact on address fields
• What it catches: "ABC Plumbing" and "ABC Plumbing LLC" at the same billing address
• What it misses: Same business with different billing addresses (home address vs. business address)

Standard Contact Matching Rule

• Fields: First Name, Last Name, Email
• Method: Exact on Email, Fuzzy on Name
• What it catches: Same person with minor name variations ("Bob" vs "Robert")
• What it misses: Same person with different email addresses

Standard Lead Matching Rule

• Fields: First Name, Last Name, Email, Company
• Method: Exact on Email, Fuzzy on Name and Company
• What it catches: Duplicate form submissions, re-imported leads
• What it misses: Leads from different email addresses for the same person/company

Activation

Navigate to Setup → Matching Rules. Standard rules are inactive by default. Activate the ones relevant to your objects. You can't edit standard rules, but you can create custom rules that supplement them.

Creating custom Matching Rules

Custom rules let you match on any standard or custom field. Common custom rules:

Phone-based Account Matching

Object: Account
Match criteria:
 - Field: Phone | Method: Exact


Why: Phone numbers are the most reliable deduplication key for local businesses. Business names have too many variations; phone numbers don't. Two accounts with the same phone number are almost certainly the same business.

Configuration note: Normalize phone formats before relying on exact phone matching. "(555) 123-4567" and "5551234567" are the same number but won't match on exact comparison without format standardization.

Domain-based Account Matching

Object: Account
Match criteria:
 - Field: Website | Method: Exact


Why: Catches accounts entered under different names but with the same website. Works for businesses with web presence; less useful for local businesses without websites.

Compound Name + City Matching

Object: Account
Match criteria:
 - Field: Account Name | Method: Fuzzy
 - Field: Billing City | Method: Exact
 - Field: Billing State | Method: Exact


Why: Prevents matching different locations of the same brand. "Neighborly" in New York and "Neighborly" in New Jersey are separate accounts — compound matching on name + city keeps them separate while still catching true duplicates within the same city.

Custom External ID Matching

Object: Account
Match criteria:
 - Field: DataLane_ID__c (custom) | Method: Exact


Why: If your enrichment provider assigns a unique identifier to each business record, use it as a match key. External IDs are the most precise deduplication identifiers available.

Configuring Duplicate Rules

Step-by-step

1. Navigate to Setup → Duplicate Rules → New Rule
2. Select the object (Account, Contact, Lead)
3. Select the Matching Rule(s) to reference
4. Configure the action:

1. Configure record-level security:
2. Compare across all records (standard) or with sharing rules (filtered)
3. For most orgs, compare across all records
4. Critical: API settings
5. "Allow alerts when creating records via the API" — Enable this
6. Without this, records created via Data Loader, integrations, and API calls bypass duplicate detection entirely

Alert vs. Block: the decision

Alert (recommended for most rules):

• Shows a warning to the user
• Allows the save with acknowledgment
• Captures duplicate match in reports
• Low friction; high adoption

Block:

• Prevents the save entirely
• User must modify the record or cancel
• Useful for high-confidence rules (exact email match) where false positives are near-zero
• Causes frustration when false positives occur; users find workarounds

Progressive approach:

1. Start with Alert on all rules
2. Monitor false positive rate for 30 days
3. Move to Block on rules with <2% false positive rate
4. Keep Alert on fuzzy matching rules (higher false positive rate)

Report option

Always enable the Report option. It creates a Duplicate Record Set for every potential duplicate identified — regardless of whether the user saves or cancels. This data feeds your duplicate monitoring and allows you to track duplicate creation patterns over time.

Duplicate Jobs: scanning existing records

Duplicate Jobs scan your existing database against active Matching Rules to find duplicates that were created before rules were active or that entered through unprotected channels.

Running a Duplicate Job

1. Navigate to Setup → Duplicate Jobs → New Job
2. Select the object to scan
3. Select the Matching Rule(s) to use
4. Run the job (large databases may take hours)
5. Review results in Duplicate Record Sets

When to run

• After initial Duplicate Rule configuration
• After every bulk import
• Quarterly as scheduled maintenance
• After enabling a new Matching Rule

Working with results

Duplicate Jobs create Duplicate Record Set records that group potential duplicates. Review these sets:

• Auto-merge candidates: High-confidence exact matches (same phone, same email)
• Review required: Fuzzy matches that need human judgment- False positives: Dismiss matches that aren't actual duplicates

Apex programmatic enforcement

For developers who need programmatic duplicate checking beyond declarative rules:

Database.DMLOptions

Database.DMLOptions dml = new Database.DMLOptions();
dml.DuplicateRuleHeader.allowSave = false;
dml.DuplicateRuleHeader.runAsCurrentUser = true;

Account acc = new Account(Name = 'ABC Plumbing', Phone = '5551234567');
Database.SaveResult sr = Database.insert(acc, dml);

if (!sr.isSuccess()) {
   for (Database.Error err : sr.getErrors()) {
       if (err instanceof Database.DuplicateError) {
           Database.DuplicateError dupErr = (Database.DuplicateError) err;
           // Access duplicate match results
           Datacloud.DuplicateResult dupResult = dupErr.getDuplicateResult();
           // Handle the duplicate programmatically
       }
   }
}


Use cases for Apex enforcement

• Custom import processes that need to check duplicates and handle matches programmatically
• Integration endpoints that should merge rather than create when duplicates are found
• Batch processes that need duplicate awareness without UI interaction

Reporting on duplicates

Standard reports

Salesforce provides a "Duplicate Record Sets" report type. Create reports showing:

• Total duplicate sets by object- Duplicate sets created per month (trend)
• Duplicate sets by Matching Rule (which rule catches the most)

Custom dashboards

Build a duplicate monitoring dashboard with:

• Duplicate creation rate: New duplicate sets per month
• ‍Merge rate: Duplicate sets resolved per month
• ‍Net duplicate trend: Creation rate minus merge rate (should be negative)
• Top duplicate sources: Which integration or import process creates the most duplicates

Where native rules hit a wall

Cross-object matching

Native rules match within an object (Account to Account, Lead to Lead). Lead-to-Account matching — the most important cross-object scenario — requires workarounds:

• Custom Matching Rules on Lead that reference Account fields (limited capability)
• Flow-based matching that queries Accounts when a Lead is created- Third-party tools (LeanData, Openprise) designed for cross-object matching

Complex entity resolution

Native fuzzy matching handles simple variations ("ABC Plumbing" vs. "ABC Plumbing LLC"). It doesn't handle:

• DBA name relationships ("Smith's HVAC" = "John Smith Heating & Cooling")
• Franchise hierarchies with location-specific naming- Abbreviation patterns ("Intl" vs. "International", "Mfg" vs. "Manufacturing")

Scale limitations

• Matching Rules process at most 5 rules per object
• Duplicate Jobs on large databases (500,000+ records) can take hours or timeout
• No batch merge in the native UI (3-record merge limit)

Monitoring gaps

• No built-in alerting when duplicate creation rate spikes
• No automated merge recommendations
• No trend analysis on duplicate patterns

Configuration checklist

• [ ] Standard Matching Rules activated for Accounts, Contacts, Leads
• [ ] Custom phone-based Matching Rule created for Accounts
• [ ] Duplicate Rules created for each active Matching Rule
• [ ] Duplicate Rules set to Alert mode (not Block, initially)
• [ ] API-created record detection enabled on all Duplicate Rules
• [ ] Report option enabled on all Duplicate Rules
• [ ] Duplicate Job run on existing database
• [ ] Results reviewed and actioned (merge, dismiss, flag)
• [ ] Phone number format standardized across records
• [ ] Monthly Duplicate Record Set report scheduled
• [ ] Data quality owner assigned to monitor and tune rules
• [ ] Integration endpoints audited for duplicate creation behavior

FAQ

What are Salesforce Duplicate Rules?

Duplicate Rules define what Salesforce does when it detects a potential duplicate during record creation or editing. They reference Matching Rules (which define detection criteria) and specify an action: Alert (warn the user), Block (prevent the save), or Report (log silently).

How do Matching Rules differ from Duplicate Rules?

Matching Rules define how to detect duplicates (which fields to compare, exact vs. fuzzy matching). Duplicate Rules define what to do about detected duplicates (alert, block, report). You need both — Matching Rules without Duplicate Rules detect silently; Duplicate Rules without Matching Rules have nothing to reference.

Do Duplicate Rules work on API-created records?

Not by default. You must explicitly enable "Allow alerts when creating records via the API" in each Duplicate Rule. Without this setting, all records created via Data Loader, integrations, and API calls bypass duplicate detection.

How many Matching Rules can I have per object?

Up to 5 active Matching Rules per object. Each can reference up to 3 match criteria (field comparisons). This limit means you need to prioritize your most impactful matching criteria.

Should I use standard or custom Matching Rules?

Both. Activate standard rules for baseline protection, then add custom rules for your specific needs. Phone-based matching is the most valuable custom rule for local business accounts.

Salesforce Duplicate Rules are the foundation of duplicate prevention — but they require thoughtful configuration. Enable API enforcement, start with alerts, monitor false positive rates, and add custom matching rules for phone and compound fields. Where native tools reach their limits, third-party tools fill the gap.