MatchingRule Metadata Type Reference

The MatchingRule metadata type defines the field comparison formula and phonetic/fuzzy algorithms that determine whether two records on an object represent the same real-world entity. Introduced in API version 33.0, MatchingRule works hand-in-hand with DuplicateRule: the MatchingRule computes the match index keys and evaluates candidate pairs, while the DuplicateRule decides whether to block or alert the user.

In Salesforce DX projects, all matching rules for an object are stored in a single per-object file at force-app/main/default/matchingRules/<ObjectName>.matchingRule-meta.xml.

Supported matchingMethod Algorithms#

Key Metadata Fields#

Production-Grade XML Example (Contact.matchingRule-meta.xml)#

Below is a MatchingRules file for Contact (force-app/main/default/matchingRules/Contact.matchingRule-meta.xml) that combines fuzzy first/last name matching with exact email or normalized phone matching:

<?xml version="1.0" encoding="UTF-8"?>
<MatchingRules xmlns="http://soap.sforce.com/2006/04/metadata">
    <matchingRules>
        <fullName>Contact_Fuzzy_Name_And_Email_Or_Phone</fullName>
        <booleanFilter>1 AND 2 AND (3 OR 4)</booleanFilter>
        <description>Matches Contacts with fuzzy First + Last Name and either Exact Email or Fuzzy Phone.</description>
        <label>Contact Fuzzy Name and Email or Phone</label>
        <matchingRuleItems>
            <blankValueBehavior>NullNotAllowed</blankValueBehavior>
            <fieldName>FirstName</fieldName>
            <matchingMethod>FirstName</matchingMethod>
        </matchingRuleItems>
        <matchingRuleItems>
            <blankValueBehavior>NullNotAllowed</blankValueBehavior>
            <fieldName>LastName</fieldName>
            <matchingMethod>LastName</matchingMethod>
        </matchingRuleItems>
        <matchingRuleItems>
            <blankValueBehavior>NullNotAllowed</blankValueBehavior>
            <fieldName>Email</fieldName>
            <matchingMethod>Exact</matchingMethod>
        </matchingRuleItems>
        <matchingRuleItems>
            <blankValueBehavior>NullNotAllowed</blankValueBehavior>
            <fieldName>Phone</fieldName>
            <matchingMethod>Phone</matchingMethod>
        </matchingRuleItems>
        <ruleStatus>Active</ruleStatus>
    </matchingRules>
</MatchingRules>

Querying MatchingRule with SOQL#

-- Inspect all MatchingRules and their indexing status
SELECT Id, DeveloperName, MasterLabel, SobjectType, RuleStatus, BooleanFilter,
       (SELECT Id, Field, MatchingMethod, BlankValueBehavior, SortOrder FROM MatchingRuleItems ORDER BY SortOrder)
FROM MatchingRule
ORDER BY SobjectType, MasterLabel

Frequently asked questions

How are MatchingRule files organized by object in SFDX?

All custom matching rules for a given object are stored in a single container file per object inside force-app/main/default/matchingRules/ObjectName.matchingRule-meta.xml.

What is the difference between Exact and Fuzzy matchingMethod values in MatchingRule?

Exact checks for an identical character match, whereas fuzzy matching methods (such as FirstName, LastName, CompanyName, Phone, Street, and City) apply phonetic algorithms, nickname dictionaries, and keyboard distance scoring to catch variations like Bob vs Robert or Acme Inc vs Acme Corp.

What does blankValueBehavior control on a MatchingRuleItem?

MatchBlank treats two records with null values in that field as a match, whereas NullNotAllowed (the recommended default) ignores the comparison if either record has a blank value in that field.

Why did my MatchingRule deploy with ruleStatus set to Activating instead of Active?

Activating a MatchingRule requires Salesforce to build an asynchronous background match index key across all existing records in the table. In large orgs, indexing completes asynchronously and transitions ruleStatus from Activating to Active.

Can I use custom fields inside a MatchingRule?

Yes. Custom Text, Email, Phone, Number, and Date fields can be used in matchingRuleItems with the Exact matchingMethod.