Fix Guide

How to Fix Salesforce Duplicate Rules Blocking Data Imports

Step-by-step fix guide with AI-powered diagnosis from BuildForce.

When a Salesforce Duplicate Rule is set to 'Block' and your import contains records that match existing data, the API throws DUPLICATES_DETECTED and rejects the records. Fix options in order of safety: deduplicate the source data BEFORE the import using SOQL to identify pre-existing matches, use the DuplicateRuleHeader with allowSave=true to bypass on a per-call basis (Salesforce still records the duplicate), tighten the matching rule's fuzzy thresholds to reduce false positives, or temporarily deactivate the duplicate rule during a controlled migration window with audit logging enabled.

DUPLICATES_DETECTEDallowSave HeaderMatching Rule FuzzinessPre-Import Dedup

Get AI-Powered Diagnosis See Pricing

Symptoms

Data Loader showing 'DUPLICATES_DETECTED: Use one of these records?' on bulk imports

Bulk API failedResults containing DUPLICATES_DETECTED for 30%+ of records

Single records inserting fine in the UI but Bulk API rejecting them

Imports succeeding in sandbox but failing in production due to additional matching records

Migration from another CRM stalling because Lead records match existing Contacts

Apex triggers throwing DmlException with DUPLICATES_DETECTED during programmatic inserts

Root Causes

Matching rule fuzziness too aggressive

Matching rules default to 'Fuzzy: First Name' and 'Fuzzy: Last Name', which match 'Bob' to 'Robert' and 'Liz' to 'Elizabeth'. For data migration, this catches too many false positives, blocking imports of distinct individuals who happen to share name variations.

Duplicate rule action set to 'Block' with no override allowed

When the rule's action is Block and 'Allow override' is unchecked, no caller (UI or API) can save the duplicate. The DuplicateRuleHeader.allowSave only works when 'Allow override' is enabled on the rule.

Cross-object matching catching unexpected records

Lead and Contact matching rules can be configured to match across objects. An import of new Leads can be blocked because the Lead's email matches an existing Contact's email — even though they're different sObject types.

Standard matching rule activated without review

Salesforce ships activated standard matching rules for Account, Contact, and Lead. Orgs that 'turn on the standard rules' inherit aggressive fuzzy matching that wasn't designed for their data shape.

Duplicate rule running on bulk-loaded records that shouldn't trigger it

Duplicate rules can be configured to run on UI-only or on all entry points including API. If 'On API edits' is checked, every Bulk API insert triggers evaluation, slowing throughput and rejecting legitimate migration data.

How to Fix It — Step by Step

Pre-deduplicate source data using SOQL match queries

Before the import, query the target org for records matching your incoming data on the matching key (usually email). Remove pre-existing rows from the import file so the duplicate rule never fires.

Example

SELECT Email FROM Contact WHERE Email IN ('a@x.com', 'b@y.com', /* batch of incoming emails */)

Bypass per-call with DuplicateRuleHeader

For one-time migrations, set Sforce-Duplicate-Rule-Header: allowSave=true on the REST request, or DuplicateRuleHeader on the SOAP API. The rule still evaluates and the duplicate is logged, but the save succeeds. Requires 'Allow override' on the rule.

Example

POST /services/data/v59.0/sobjects/Lead
Sforce-Duplicate-Rule-Header: allowSave=true; includeRecordDetails=false; runAsCurrentUser=false
Content-Type: application/json
{
  "FirstName": "Robert",
  "LastName": "Smith",
  "Email": "r.smith@example.com"
}

Audit the matching rule fields and fuzziness

Open Setup → Duplicate Management → Matching Rules. For each field, review the match method (Exact, Fuzzy, FuzzyFirstName, FuzzyLastName, EditDistance). Tighten to 'Exact' for migration windows where false positives outweigh false negatives.

Enable 'Allow override' on the duplicate rule

In Setup → Duplicate Management → Duplicate Rules → [Rule] → Actions, check 'Allow' next to the 'On Create' / 'On Edit' actions. This is what enables the allowSave header to work without deactivating the rule entirely.

Disable 'Run on API edits' for bulk imports

In the duplicate rule's Actions section, uncheck 'Run rule on edits via API' for the duration of the migration. This bypasses the rule for all API entry points while keeping UI protection active. Re-enable immediately after migration.

Re-process records that hit the rule into a quarantine table

Instead of dropping records that fail with DUPLICATES_DETECTED, write them to a quarantine sObject with the matching record IDs. A data steward can review and decide to merge, link, or override per record.

Validate post-import with a duplicate count baseline

After the import, run a duplicate count audit. Compare to the pre-import baseline. If the count grew despite the rule, your matching criteria missed cases — tighten and run a remediation merge.

Example

SELECT Email, COUNT(Id) cnt FROM Contact WHERE CreatedDate = TODAY GROUP BY Email HAVING COUNT(Id) > 1

Let BuildForce diagnose and fix this automatically

Instead of following manual steps, connect your org and let our AI identify exactly what's broken and how to fix it — in minutes.

Book a Demo

Common Questions

More answers about this issue and how to resolve it.

Stop debugging manually. Let AI do it.

BuildForce runs 200+ automated checks across your Salesforce org and tells you exactly what's broken and how to fix it.

Book a Demo View Pricing