DUPLICATES_DETECTED" salesforce lead insert error

TL;DR

The insert was blocked because an active duplicate rule found a likely match and its action is set to Block. Read the duplicate result to get the matched record id, then either update the existing lead instead of inserting or, if it is a false positive, loosen the matching rule. Only the Alert action can be bypassed via the API; Block cannot.

Error

[ {
  "message" : "Use one of these records?",
  "errorCode" : "DUPLICATES_DETECTED",
  "fields" : [ ]
} ]

Steps

1. Capture the full save response. The payload includes a duplicateResult with matchResults and the matched record ids. Expected: you have the existing lead id in hand.
2. Open the matched record and compare email, company, and name against the row you tried to insert. Expected: you can say whether it is a true duplicate or a false positive.
3. If it is a true duplicate, update the existing lead (PATCH the record id) instead of inserting. Expected: the update returns 204 and no new lead is created.
4. If it is a false positive and the rule action is Alert, set the DuplicateRuleHeader allowSave flag to true on retry. Expected: the insert succeeds and the bypass is logged.
5. If the rule action is Block, no API flag bypasses it. Ask the admin to change the action to Alert or to narrow the matching rule (for example, require exact email plus company instead of fuzzy name). Expected: legitimate inserts pass and true duplicates still get flagged.

When to use

• Lead, contact, or account inserts fail with errorCode DUPLICATES_DETECTED.
• An agent doing bulk lead loads keeps hitting the same rejection on repeat rows.
• You see "Use one of these records?" in the UI on manual entry.

When not to use

• The error is DUPLICATE_VALUE on upsert (external id collision, different fix).
• HubSpot CONTACTALREADYEXISTS (HubSpot dedupes by email, different flow).
• You actually want duplicates (then disable or scope down the rule, do not bypass per row).

Tool compatibility

• Salesforce REST and SOAP APIs, API version 50 and later.
• Duplicate rules and matching rules configured in Setup on Lead, Contact, and Account.
• Data Loader and ETL tools that surface saveResult arrays.

Variant phrasings

Use one of these records?

The UI wording for the same duplicate-rule hit; the API returns DUPLICATES_DETECTED.

DUPLICATES_DETECTED with allowSave

Setting the duplicate rule header to allow save bypasses Alert-action rules only; Block still rejects.

Why it happens

Duplicate rules run on insert and compare the new record against matching-rule criteria (fuzzy name, exact email, and similar). When a match scores above the threshold, the rule action decides: Allow just reports, Alert warns but permits bypass, Block rejects outright.

Edge cases

• Person accounts and leads with the same email as a contact can trigger cross-object matching rules; check the rule scope, not just the object.
• Matching rules ignore middle names and common nicknames poorly; expect false positives on short names like "Li" or "Kim".
• allowSave=true on a Block rule silently does nothing; the insert still fails, so confirm the rule action before retrying.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstXkl9UrrSH0LwQRrZMbF6g