Salesforce duplicate rules: what they do to imports and APIs

Salesforce splits duplicate management into two parts that only work together. A matching rule compares a record with the records already in Salesforce and says which ones are duplicates. A duplicate rule names the object it watches, picks one or more matching rules, and sets what happens when a person creates or edits a record that matches. Salesforce's help describes the two as a pair: the matching rule finds, the duplicate rule handles.

Both come built in for accounts, contacts and leads, and the standard ones are active by default. You can edit them or add your own in Setup. Duplicate rules are in Essentials, Professional, Enterprise, Performance, Unlimited and Developer editions.

The standard lead duplicate rule doesn't only look at leads. In an org created in Summer '17 or later, it matches leads that duplicate other leads and contacts that duplicate leads, and the standard contact rule does the same the other way around. Older orgs can switch the same behavior on in Setup. So a new lead for someone who is already a contact counts as a duplicate, even though there is no other lead.

Out of the box, both rules are set to Allow on create, which means a person is alerted but can save the record, and to Allow on edit.

What counts as a match is set by the standard contact and lead matching rules. They never match on email alone: every line of the equation needs the person's name as well, plus one more thing. Salesforce's equation for leads is any one of these:

Say a contact is already in Salesforce (the names here are made up): Maria Lopez, Head of Operations at Northwind Traders, maria.lopez@northwind.example, (415) 555-0182. Here is what happens to four new lead rows, first under a lookup by email on leads (what a lead import set to match by email does), then under the standard lead rule.

Each duplicate rule has an action on create and an action on edit. Allow lets the record be saved, Block stops the save, and you can turn on an alert, a report or both. When you create a rule, Salesforce's defaults are to alert on create and report on create and edit.

The alert is what a person sees in Salesforce: a message (the standard rules say "Use one of these records?") and, in Lightning Experience, up to 15 possible duplicates to open instead. Report puts the saved record and its duplicates, up to 100 for each matching rule, into a duplicate record set, including records on the other object for a cross-object rule. That is the list the duplicate reports are built from.

The right-hand column is where an import or API write differs:

You need the Customize Application permission to create, edit, activate or deactivate a rule. These are the steps in Salesforce's help, read October 2026; they apply to editing a standard rule as well as making a new one.

A matching rule is where you change what counts as a duplicate. You need the Customize Application permission. These are the steps in Salesforce's help, read 14 October 2026. Salesforce suggests making the duplicate rule first and clicking Create New Matching Rule from inside it, so Salesforce attaches it to that duplicate rule automatically.

Each field in the rule gets a matching method. Exact works on almost any field, custom fields included, and only lowercases the value and trims spaces before comparing. The similarity methods exist for a few standard fields only. In the Matching Method list, each similarity method's label ends with its field's name, after a colon, such as the one ending ": First Name". This page calls that the First Name similarity method. A field counts as a match when its score reaches the method's threshold, listed in the table under the steps.

These four rules catch duplicates the standard rules let through. Each row is a matching rule and the duplicate rule that uses it; make the duplicate rule, then its matching rule from inside it, as above. Keep the standard rules active beside them: an object can have five active duplicate rules, and each duplicate rule can use up to three matching rules, one for each object it compares with. The methods and limits are from Salesforce's matching rule pages, read 14 October 2026.

The action in the right-hand column is for people working in Salesforce. For rows from an import or the API, a match is refused under Allow with an alert as well as under Block, as the import section below explains, so a new rule also changes what your next load can create.

Same email: the standard rules need the person's name as well, so a lead with a contact's email under another name is saved. This rule catches it. Map Lead Email to Email when you pick the contact rule. A shared inbox such as info@ is a real exception, so check for those before choosing Block.

Similar name at the same company: all three fields use similarity methods, which suits names spelled two ways at one company. Similarity also finds some people who aren't the same, so alert rather than block, and use it only for names in Latin characters.

Phone and last name: Salesforce's own example scores 1-415-555-1234 against 1-415-555-5678 at 90, a match, because the last four digits carry only 10% of the score. Phone alone would match everyone at one office, so the rule adds the last name. For international data, Salesforce recommends Exact, which needs the numbers stored in one format.

Same account name: Exact only lowercases and trims, so Acme Inc and Acme Inc. are different to it. Clean account names before relying on it, or use the Company Name similarity method and alert instead. Block stops anyone saving a second account with that name, so use it only if your org treats one name as one account; otherwise alert.

Salesforce lists the cases where a duplicate rule's setting is overridden. In its words: "no alert is shown and users can't save records" when "Records are added using the data import tools" or "Records are added or edited using Salesforce APIs." There is nobody to show an alert to, so the save that Allow would have permitted doesn't happen either. Data Loader is covered both ways: it is a bulk import tool, and by default it loads through Salesforce's SOAP API.

Salesforce's own support article on campaign imports shows it. Its rule is set to "Allow | Alert and Report", yet the import email reads "Leads created: 0" with two lines of "You're creating a duplicate record. We recommend you use an existing record instead." The import finishes, and the matching rows are refused, not imported.

Three points from Salesforce's notes on duplicate rules, and one from its Data Import Wizard help, matter for a load:

Operelio pushes into Salesforce through its API, so this is the case we see. On one live push of leads on 7 August 2026, our preview counted 20 new leads to create, and 9 were created. Salesforce's duplicate rule refused the other 11, and each of them matched a contact already in the org, not a lead. That is the cross-object match the standard lead rule makes.

Our lookup had matched on email against leads, as a lead import does, and found nothing for those 11 people, so it sent them as new. Salesforce compared them with contacts too and refused them. The 9 that weren't refused were created as normal, because each row in a push succeeds or fails on its own.

Since then our preview also searches contacts and leads by company before a push and flags new rows with a similar name to someone already at the same company, so a row like that can be dealt with before it is sent.

Most of this happens before the import starts. The first four steps suit every load. The last two take the rule out of the way for one load, which only makes sense once the file itself is clean.

Duplicate reports read from duplicate record sets, so they show the records a rule reported, records someone added to a set by hand, and the results of duplicate jobs. Nothing refused by an import is in them. You need the Manage Custom Report Types permission.

These limits are from Salesforce's notes on duplicate rules and on matching rules, read October 2026.

Rules stop new duplicates. The ones already there are merged by hand, from a record, in Lightning Experience. Merging leads needs Delete on leads, and merging contacts needs Delete on contacts.

The merged record keeps the Created By and Created Date of the oldest record, related items such as campaigns and activities move to it, and the other leads go to the Recycle Bin.

To find duplicates across the whole org instead of one record at a time, Salesforce has duplicate jobs, but only in Performance and Unlimited editions. On other editions, a report on duplicate record sets or a dedupe app is the way to find them in bulk.

Operelio pushes a cleaned file into Salesforce leads or contacts through the API, so your duplicate rules apply to every row it sends, and today a rule set to Allow with an alert refuses a matching row just as a Block rule does. What the push does around that: