Salesforce Apex: Bypass Duplicate Rules

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.

Table of Contents

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.

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 record.”

Bypass Duplicate Rules Using Salesforce Apex

Below, I will provide an example and a step-by-step explanation of how to bypass the duplicate rule using Salesforce Apex.

Without Bypassing Duplicate Rule

First, let’s understand what error we may face if we bypass the duplicate rule while creating or updating records using Salesforce Apex.

For example, you have a web form where people can request a product demo. Every time someone fills out the form, your system creates a lead in Salesforce using Apex code.

But Salesforce has a rule that blocks duplicate leads, for example, if the same email address is used more than once.

So, if the same person submits the form again, Salesforce throws a duplicate error, and the new Lead is not created.

Below, I created an Apex class with a method, and in the try block, I instantiated a lead object and populated its fields to create a new lead record.

After that, we used the INSERT DML operation to create the lead record, and if any error occurred, we handled that exception in the catch block.

public class BypassDuplicateRule {
    
    public void withoutBypass(){
        
        try {
            Lead newLead = new Lead(
                FirstName = 'John',
                LastName = 'Doe',
                Email = 'john.doe@gmail.com',
                Company = 'Test Company'
            );                    
            
            Database.insert(newLead);
            
            System.debug('Lead created successfully: ' + newLead.Id);
            
        } catch (Exception e) {
            System.debug('Error while creating Lead: ' + e.getMessage());
        }
    }
}

To execute the code, you need to open an anonymous window in the developer console, create the class instance, and call the method that you want to execute.

In the image below, you can see that when I executed the above Apex code to create the lead record, I encountered an error stating that the record is a duplicate because a lead record already exists in the Lead object.

With Bypass Duplicate Rules Using Salesforce Apex

Now, let’s understand how we can use Salesforce Apex to bypass the duplicate rule and create the records.

Here is the Database.DMLOptions creates a special object called dmlOpts that allows you to set extra options for a DML operation (such as insert, update, or delete).

Then, allowSave = true allows even if this record is a duplicate (e.g., the same email as another Lead), and it proceeds to save it. This helps bypass the duplicate rule.

The runAsCurrentUser = false doesn’t apply duplicate rules based on the current user’s permissions or settings. Use system-level behavior instead.

This is very important because if runAsCurrentUser = true (default), Salesforce still applies the duplicate rules for that user, and your bypass won’t work.

public class BypassDuplicateRule {
    
    public void withBypass(){
        
        try {
            Lead newLead = new Lead(
                FirstName = 'John',
                LastName = 'Doe',
                Email = 'john.doe@gmail.com',
                Company = 'Test Company'
            );
            
            Database.DMLOptions dmlOpts = new Database.DMLOptions();
            dmlOpts.DuplicateRuleHeader.allowSave = true;
            dmlOpts.DuplicateRuleHeader.runAsCurrentUser = false;
            
            newLead.setOptions(dmlOpts);
            
            Database.insert(newLead);
            
            System.debug('Lead created successfully: ' + newLead.Id);
            
        } catch (Exception e) {
            System.debug('Error while creating Lead: ' + e.getMessage());
        }
    }
}

After executing the above code, you can see the debug log, which displays the newly created lead ID.

How to Bypass Duplicate Rules Using Salesforce Apex

Additionally, you can see in the lead object that we have two lead records with the same value, indicating that we have successfully bypassed the duplicate rule using Salesforce Apex.

Conclusion

I hope you have got an idea about how to bypass duplicate rules using Salesforce Apex. In that, I have provided a real-time example and a step-by-step explanation for creating or updating duplicate records in Salesforce, even when a duplicate rule is applied to the object.