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.

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