Bypass Duplicate Rules Using Salesforce Apex

by

You may face a duplicate error when creating or updating records using Apex code in Salesforce. This happens when Duplicate Rules are active and detect a matching record.

In some cases, you may want to bypass these duplicate rules, such as during data import, integration, or when implementing specific business logic.

In this tutorial, we will learn how to bypass duplicate rules using Salesforce Apex. In that, I will explain a real-time example and a step-by-step explanation.

What are Duplicate Rules in Salesforce?

Salesforce duplicate rules help prevent users from creating or updating records that already exist in the system, ensuring data integrity. These rules check for duplicates using matching criteria, such as matching email addresses, phone numbers, or names.

For example, if the user tries to create a lead with an email address that already exists, Salesforce will block the record and display a duplicate error.

Important points you should know:

  • The bypass method works only in Apex code, not in the UI or Salesforce Flow.
  • Make sure your duplicate rule is set to “Allow”, not “Block.” If the rule blocks records completely, Apex can’t bypass it.
  • To check this, go to: Setup -> Duplicate Rules -> Select the rule that you created.
Lead Duplicate Rule in Salesforce
  • In the rule settings, make sure the action on create/update is set to “Allow”.
  • You can choose to show a warning or report duplicates, but it must allow saving.
  • If you have multiple matching rules, Apex will bypass all of them during the insert or update.

What Does “Bypass Duplicate Rules Using Salesforce Apex” Mean?

In Salesforce, duplicate rules help prevent users from creating or updating records with the same data (like duplicate Leads or Accounts).

But sometimes, when you’re creating or updating records using Apex code, these rules can block your operation by throwing a duplicate error. Bypassing duplicate rules means writing Apex code in a way that ignores or skips these duplicate checks when needed.

Let’s say you are building an integration that automatically creates Lead records from a web form.

Salesforce has a duplicate rule that blocks Leads with the same email address. But in your case, you want to allow the system to create those Leads even if the email already exists, for logging or tracking purposes.

In such a case, you can bypass the duplicate rule in Apex by using a special field called:

DmlOptions.DuplicateRuleHeader.allowSave = true;

This is used in Apex when performing a DML operation (such as insert or update), and you want to bypass duplicate rules.

  • DmlOptions:
    • This is a special object in Apex that allows you to set additional options when saving records.
  • DuplicateRuleHeader:
    • This is a part of DmlOptions used to control how duplicate rules behave.
  • allowSave = true:
    • This tells Salesforce, “Even if a duplicate is found, still save the