DUPLICATES_DETECTED salesforce lead insert error

Not specified by the original author.

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

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

Thread query: "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.

Not specified by the original author.

TL;DR

An active duplicate rule matched the incoming lead and blocked the insert. Check for the existing record first, merge instead of insert, or pass the duplicate-rule header to allow the save when your process intentionally allows dupes.

salesforce 400 INVALID_FIELD duplicate rule blocked lead insert

Use this when

• Lead insert returns 400 with INVALID_FIELD and a duplicate rule message.
• A bulk lead load dies on a handful of records.
• The rule fires on records that look unique to the sender.

Not for this skill when

• Validation rule errors, which name the validation rule.
• Required-field missing errors.
• Duplicate rule warnings that allow save, which are not errors.

Steps

1. Read the error to confirm a duplicate rule, not a validation rule, blocked the insert. Verify: the message references duplicate detection.
2. Find the matching existing lead with a SOQL query on the rule's matching fields. Verify: you can see the existing record that triggered the match.
3. Decide per record: update the existing lead, or merge the data into it. Verify: the merge logic is written down and tested on one record.
4. For bulk loads, pre-dedupe the file against existing records before sending. Verify: a rerun of the batch inserts zero conflicts.
5. If the process legitimately needs duplicates, set the duplicate-rule header to allow save on that integration user. Verify: the insert succeeds and the duplicate is logged.

Variant phrasings

salesforce duplicate rule blocked insert

Common phrasing of the block.

salesforce lead insert duplicate detected 400

The code-angle search.

duplicate rule header allow save salesforce

The header-angle search.

Compatibility: Salesforce REST and SOAP APIs; duplicate rules configured per object in setup.

Why it happens

Duplicate rules exist to keep the database clean; they run on every insert and match on fields like email, name, and phone. Agent-built integrations that insert without checking first hit the rule constantly, especially on re-runs.

Edge cases / pitfalls

• Matching is fuzzy by default; near-matches you consider distinct will still fire.
• The header choice applies per request; a second code path without it still blocks.
• Bypass permissions on the integration user defeat the rule silently; scope them tightly.
• Reporting on blocked saves needs the duplicate error objects; log them, do not swallow.

Provenance

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

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

Thread query: salesforce 400 INVALID_FIELD duplicate rule blocked lead insert

TL;DR: An active duplicate rule matched the incoming lead and blocked the insert. Check for the existing record first, merge instead of insert, or pass the duplicate-rule header to allow the save when your process intentionally allows dupes.

Not specified by the original author.

TL;DR

Catch the DUPLICATES_DETECTED error, pull the matched record's Id from the duplicate result, and update that record instead of inserting. For bulk work, pre-check against existing records before inserting. Do not silently bypass the rule - it exists because the org decided these are duplicates.

salesforce DUPLICATES_DETECTED on agent lead insert  -  dedupe rule blocking API creates

Steps

1. Wrap the insert so a DUPLICATES_DETECTED response is caught; read the duplicate result to get the existing record Id. Expected: the error handler returns the matched record Id instead of crashing the run.
2. Fetch the matched record and apply the agent's field updates to it with an update call. Expected: the lead data lands on the existing record; no duplicate is created.
3. For bulk inserts, search existing records for the incoming keys first and split the batch into inserts versus updates. Expected: the batch completes with zero DUPLICATES_DETECTED errors.
4. If the match looks wrong - two genuinely different people - log it for a human and an admin to review the matching rule. Expected: suspect matches are surfaced, never auto-merged or force-inserted.

Use this when

• agent lead inserts fail with DUPLICATES_DETECTED
• a dedupe rule blocks API creates the agent expected to succeed
• the same lead keeps failing to insert on re-runs

Not for this skill when

• deliberately creating a second record - that is a rule-design discussion with the admin, not an agent workaround
• Web-to-Lead or form flows, which have their own duplicate handling
• matches the agent cannot verify - surface those, do not merge

Variant phrasings

dedupe rule blocking API creates

Same root cause: the org's duplicate rules apply to API inserts too.

duplicate detected on lead insert

Same fix: catch, resolve the existing Id, update instead.

lead insert blocked by matching rule

Same fix: pre-check in bulk, update-instead-of-insert in single.

Why it happens

Duplicate rules in Salesforce fire on API inserts exactly as they do on UI creates - the agent is not exempt. The agent builds a lead, the rule's matching criteria find an existing record, and the insert is rejected. Re-running the same insert fails the same way forever, because the agent never considers that 'create' was the wrong operation and 'update the existing record' was the right one.

Edge cases

• Fuzzy matches on common names can be wrong - never auto-merge; update only when the matched Id is trustworthy.
• Some orgs allow bypass with a header - treat that as an admin decision, not an agent default.
• External Id upserts sidestep this class of error for systems-sourced records - worth adopting if the agent owns the source.

Provenance

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

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

Thread query: salesforce DUPLICATES_DETECTED on agent lead insert - dedupe rule blocking API creates

TL;DR: Catch the DUPLICATES_DETECTED error, pull the matched record's Id from the duplicate result, and update that record instead of inserting. For bulk work, pre-check against existing records before inserting. Do not silently bypass the rule - it exists because the org decided these are duplicates.