---
schema_version: "1"
id: 638bfb698ecad63395353ed2ae0e526d65c384977707fa5b451a34ebb70980a2
title: DuplicateRule
collection: legacydeveloper
version: current
locale: en-us
portal_url: https://docs.salesforce.com/legacydeveloper/current/en-us/api_meta/meta_duplicaterule.md
canonical_url: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_duplicaterule.htm
source_site: developer.salesforce.com
content_type: documentation
content_hash: c4e89edbddaa41f85bff5b91bb170601178657925f189cb1ad4328cf292ad077
description: Represents a rule that specifies how duplicate records in an object are detected. This type extends the Metadata metadata type and inherits its fullName field.
---
# DuplicateRule

Represents a rule that specifies how duplicate records in an object are detected. This type extends the Metadata metadata type and inherits its fullName field.

![Important](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note_important.png)

#### Important

Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

## File Suffix and Directory Location

DuplicateRule components have the .duplicateRule suffix and are stored in the duplicateRules/ directory. The name of the component file is based on the name of the object associated with the rule. For example, the component file name duplicateRules/Account.Standard\_Account\_Duplicate\_Rule.duplicateRule describes a duplicate rule component associated with the Account object.

## Version

DuplicateRule components are available in API version 68.0 and later.

## Fields

<table class="featureTable sort_table" summary="">



          <thead class="thead sorted" align="left">
            <tr>
              <th class="featureTableHeader  " id="d399266e101">Field Name</th>

              <th class="featureTableHeader  " id="d399266e104">Field Type</th>

              <th class="featureTableHeader  " id="d399266e107">Description</th>

            </tr>

          </thead>

          <tbody class="tbody">
            <tr>
              <td class="entry" headers="d399266e101" data-title="Field Name"><span class="keyword parmname" id="actionOnInsert"><a name="actionOnInsert"><!-- --></a>actionOnInsert</span></td>

              <td class="entry" headers="d399266e104" data-title="Field Type">DupeActionType (<a class="xref" href="https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_objects_intro.htm#enumeration_title">enumeration</a> of type
                string)</td>

              <td class="entry" headers="d399266e107" data-title="Description">Required. Determines what the duplicate rule does when users or the
                DuplicateRule API try to insert a record that is a duplicate. Valid values are:<dl class="dl detailList">

                  <dt class="dt dlterm"><samp class="codeph nolang" id="insertActionAllow"><a name="insertActionAllow"><!-- --></a>Allow</samp></dt>

                  <dd class="dd">For users, if <span class="keyword parmname">operationsOnInsert</span> is set to <samp class="codeph nolang">alert</samp>, the UI displays the value of <span class="keyword parmname">alertText</span> in a dialog. The dialog prompts
                    users to continue or cancel. If the user chooses to continue, the insertion
                    proceeds. If the user chooses to cancel, the record isn’t inserted.<p class="p">The
                      DuplicateRule API returns an error code and a message. To complete the
                      insertion, the code must set the <span class="keyword parmname">allowSave</span> field in
                      DuplicateRuleHeader to <samp class="codeph nolang">true</samp>
                      and reissue the request.</p>
                    <p class="p">If
                      <span class="keyword parmname">operationsOnInsert</span>isn’t set to <samp class="codeph nolang">alert</samp>, the UI inserts the record without
                      issuing an alert. The API inserts the record and doesn’t return an error
                      code.
                    </p>
                  </dd>



                  <dt class="dt dlterm"><samp class="codeph nolang">Block</samp></dt>

                  <dd class="dd">For users, the UI displays an error message and prevents them from inserting
                    the new record. The DuplicateRule API returns an error and doesn’t insert the
                    record. </dd>


                </dl>
              </td>

            </tr>

            <tr>
              <td class="entry" headers="d399266e101" data-title="Field Name"><span class="keyword parmname" id="actionOnUpdate"><a name="actionOnUpdate"><!-- --></a>actionOnUpdate</span></td>

              <td class="entry" headers="d399266e104" data-title="Field Type">DupeActionType (<a class="xref" href="https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_objects_intro.htm#enumeration_title">enumeration</a> of type
                string)</td>

              <td class="entry" headers="d399266e107" data-title="Description">Required. Determines what the duplicate rule does when users or the
                DuplicateRule API try to update a record, and the result is a duplicate. Valid
                values are:<dl class="dl detailList">

                  <dt class="dt dlterm"><samp class="codeph nolang" id="updateActionAllow"><a name="updateActionAllow"><!-- --></a>Allow</samp></dt>

                  <dd class="dd">For users, if <span class="keyword parmname">operationsOnUpdate</span> is set to <samp class="codeph nolang">alert</samp>, the UI displays the value of
                    <span class="keyword parmname">alertText</span> in a dialog. The dialog prompts users to
                    continue or cancel. If the user chooses to continue, the update proceeds. If
                    the user chooses to cancel, the record isn’t updated.<p class="p">The DuplicateRule API
                      returns a message. To complete the update, the code must set the
                      <span class="keyword parmname">allowSave</span> field in DuplicateRuleHeader to <samp class="codeph nolang">true</samp>
                      and reissue the request.
                    </p>
                    <p class="p">If
                      <span class="keyword parmname">operationsOnUpdate</span>isn’t set to <samp class="codeph nolang">alert</samp>, the UI updates the record without
                      issuing an alert. The API updates the record and doesn’t return an error
                      code.
                    </p>
                  </dd>



                  <dt class="dt dlterm"><samp class="codeph nolang">Block</samp></dt>

                  <dd class="dd">For users, the UI displays an error message and prevents them from
                    continuing. The DuplicateRule API returns an error.</dd>


                </dl>
              </td>

            </tr>

            <tr>
              <td class="entry" headers="d399266e101" data-title="Field Name"><span class="keyword parmname" id="alertText"><a name="alertText"><!-- --></a>alertText</span></td>

              <td class="entry" headers="d399266e104" data-title="Field Type">string</td>

              <td class="entry" headers="d399266e107" data-title="Description">Text that’s sent when the duplicate rule is triggered. The text is only sent if
                <span class="keyword parmname">isActive</span> is <samp class="codeph nolang">true</samp>. In the
                UI, the text displays as a message. The DuplicateRule API returns the message in its
                response. <p class="p">You can set a value for <span class="keyword parmname">alertText</span> only when you
                  have <span class="keyword parmname">actionOnInsert</span> or <span class="keyword parmname">actionOnUpdate</span>
                  (or both) set to <samp class="codeph nolang">Allow</samp>. Otherwise, you
                  receive a validation error when you add or update this component.</p>
              </td>

            </tr>

            <tr>
              <td class="entry" headers="d399266e101" data-title="Field Name"><span class="keyword parmname">description</span></td>

              <td class="entry" headers="d399266e104" data-title="Field Type">string</td>

              <td class="entry" headers="d399266e107" data-title="Description">Required. Text that describes the duplicate rule. The value is
                customer-supplied, but isn’t visible in the UI.</td>

            </tr>

            <tr>
              <td class="entry" headers="d399266e101" data-title="Field Name"><span class="keyword parmname">duplicateRuleFilter</span></td>

              <td class="entry" headers="d399266e104" data-title="Field Type"><a class="xref" href="#DuplicateRuleFilter">DuplicateRuleFilter</a></td>

              <td class="entry" headers="d399266e107" data-title="Description">Required. Criteria that define how to find records to consider when looking for
                duplicates. For example, use <span class="keyword parmname">duplicateRuleFilter</span> to exclude
                records from the match when looking for duplicates.</td>

            </tr>

            <tr>
              <td class="entry" headers="d399266e101" data-title="Field Name"><span class="keyword parmname">duplicateRuleMatchRules</span></td>

              <td class="entry" headers="d399266e104" data-title="Field Type">
                <a class="xref" href="#DuplicateRuleMatchRule">DuplicateRuleMatchRule</a>[]
              </td>

              <td class="entry" headers="d399266e107" data-title="Description">Required. One or more <a class="xref" href="https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_matchingrule.htm" title="Represents a matching rule that is used to identify duplicate records.">MatchingRule</a> components for
                the DuplicateRule. A <samp class="codeph nolang">MatchingRule</samp> controls what
                constitutes a match between records.</td>

            </tr>

            <tr>
              <td class="entry" headers="d399266e101" data-title="Field Name"><span class="keyword parmname">isActive</span></td>

              <td class="entry" headers="d399266e104" data-title="Field Type">boolean</td>

              <td class="entry" headers="d399266e107" data-title="Description">Required. If <samp class="codeph nolang">true</samp>, the DuplicateRule
                detects duplicate records. Otherwise, the rule has no effect.</td>

            </tr>

            <tr>
              <td class="entry" headers="d399266e101" data-title="Field Name"><span class="keyword parmname">masterLabel</span></td>

              <td class="entry" headers="d399266e104" data-title="Field Type">string</td>

              <td class="entry" headers="d399266e107" data-title="Description">Required. Label for this DuplicateRule. This value is the internal label for
                the rule.</td>

            </tr>

            <tr>
              <td class="entry" headers="d399266e101" data-title="Field Name"><span class="keyword parmname" id="operationsOnInsert"><a name="operationsOnInsert"><!-- --></a>operationsOnInsert</span></td>

              <td class="entry" headers="d399266e104" data-title="Field Type">string[]</td>

              <td class="entry" headers="d399266e107" data-title="Description">Required. Controls the action to take when <span class="keyword parmname">actionOnInsert</span>
                is set to <samp class="codeph nolang">Allow</samp> and the duplicate rule is
                triggered. Either one or both of these values can be set in the array:<dl class="dl detailList">

                  <dt class="dt dlterm"><samp class="codeph nolang">alert</samp></dt>

                  <dd class="dd">If set, the action specified in <span class="keyword parmname">actionOnInsert</span> occurs;
                    otherwise, the insert proceeds.</dd>



                  <dt class="dt dlterm"><samp class="codeph nolang">report</samp></dt>

                  <dd class="dd">If set, the insert operation is added to the report of duplicates.</dd>


                </dl>
              </td>

            </tr>

            <tr>
              <td class="entry" headers="d399266e101" data-title="Field Name"><span class="keyword parmname" id="operationsOnUpdate"><a name="operationsOnUpdate"><!-- --></a>operationsOnUpdate</span></td>

              <td class="entry" headers="d399266e104" data-title="Field Type">string[]</td>

              <td class="entry" headers="d399266e107" data-title="Description">Required. Controls the action to take when <span class="keyword parmname">actionOnUpdate</span>
                is set to <samp class="codeph nolang">Allow</samp> and the duplicate rule is
                triggered. Either one or both of these values can be set in the array:<dl class="dl detailList">

                  <dt class="dt dlterm"><samp class="codeph nolang">alert</samp></dt>

                  <dd class="dd">If set, the action specified in <span class="keyword parmname">actionOnUpdate</span> occurs;
                    otherwise, the update proceeds.</dd>



                  <dt class="dt dlterm"><samp class="codeph nolang">report</samp></dt>

                  <dd class="dd">If set, the update operation is added to the report of duplicates.</dd>


                </dl>
              </td>

            </tr>

            <tr>
              <td class="entry" headers="d399266e101" data-title="Field Name"><span class="keyword parmname">securityOption</span></td>

              <td class="entry" headers="d399266e104" data-title="Field Type">DupeSecurityOptionType (<a class="xref" href="https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_objects_intro.htm#enumeration_title">enumeration</a> of type
                string)</td>

              <td class="entry" headers="d399266e107" data-title="Description">Required. Determines how record sharing rules affect duplicate management.
                Valid values are:<dl class="dl detailList">

                  <dt class="dt dlterm"><samp class="codeph nolang">EnforceSharingRules</samp></dt>

                  <dd class="dd">Sharing rules affect duplicate management. If a duplicate rule is triggered
                    because an insert or update duplicates an existing record, but the running
                    user doesn’t have sharing access to that record, the insert or update
                    proceeds. The sharing rule doesn’t prevent the user from creating or updating
                    the record because the record is hidden from the user. No message is
                    issued.</dd>



                  <dt class="dt dlterm"><samp class="codeph nolang">BypassSharingRules</samp></dt>

                  <dd class="dd">Sharing rules don’t affect duplicate management. If a duplicate rule is
                    triggered because an insert or update duplicates an existing record, sharing
                    rules are ignored, but other access restrictions apply.</dd>


                </dl>
              </td>

            </tr>

            <tr>
              <td class="entry" headers="d399266e101" data-title="Field Name"><span class="keyword parmname">sortOrder</span></td>

              <td class="entry" headers="d399266e104" data-title="Field Type">int</td>

              <td class="entry" headers="d399266e107" data-title="Description">Required. Determines the order in which duplicate rules are applied.</td>

            </tr>

          </tbody>

        </table>

## DuplicateRuleMatchRule

Describes the [MatchingRule](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_matchingrule.htm#meta_matchingrule "Represents a matching rule that is used to identify duplicate records.") associated with the DuplicateRule. The MatchingRule identifies duplicate records.

| Field Name | Field Type | Description |
| --- | --- | --- |
| matchRuleSObjectType | string | Required. The name of the target object of the matching rule. For example, if you define a duplicate rule for Contact records, and you want to match with Lead records, the value of matchRuleSObjectType is Lead. |
| matchingRule | string | Required. Value that corresponds to the value of developerName in the [MatchingRule](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_matchingrule.htm "Represents a matching rule that is used to identify duplicate records.") for this duplicate rule. |
| objectMapping | [ObjectMapping](#ObjectMapping) | Required. Foreign key to an [ObjectMapping](#ObjectMapping) that maps fields from the duplicate rule’s object to fields in the target object specified by matchRuleSObjectType. |

## DuplicateRuleFilter

Specifies filter criteria for a DuplicateRule. Salesforce only applies the DuplicateRule if the record matches the criteria.

| Field Name | Field Type | Description |
| --- | --- | --- |
| booleanFilter | string | Required. A string of boolean operators that establishes the filter logic for the filter items specified in duplicateRuleFilterItems. |
| duplicateRuleFilterItems | [DuplicateRuleFilterItem](#DuplicateRuleFilterItem)\[\] | Required. A list of [DuplicateRuleFilterItem](#DuplicateRuleFilterItem) components. |

## DuplicateRuleFilterItem

This type extends the [FilterItem](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/customfield.htm#filteritem) type and inherits all its fields.

| Field Name | Field Type | Description |
| --- | --- | --- |
| sortOrder | int | Required. The order of this item in the duplicate rule filter. |
| table | string | Required. The object that has the field specified in the field field of [DuplicateRuleFilterItem.](#DuplicateRuleFilterItem) See the documentation for [FilterItem](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/customfield.htm#filteritem) for the definition of field. |

## ObjectMapping

Represents a map of fields in the input object of the DuplicateRule to fields in the output object of DuplicateRule. The input object is the object associated with the DuplicateRule. The output object can be the same object or a different object with similar fields.

For example, you can have a DuplicateRule that looks for duplicates between the Contact object and the Lead object. In this case, the input object is Contact, and the output object is Lead.

| Field Name | Field Type | Description |
| --- | --- | --- |
| inputObject | string | Required. The input object for the duplicate rule. The DuplicateRule is associated with this object. For example, if you define a duplicate rule for Contact records, and you want to match with Lead records, the value of inputObject is Contact. |
| mappingFields | [ObjectMappingField](#ObjectMappingField)\[\] | Required. The mapping of source object fields to target object fields for the duplicate rule. |
| outputObject | string | Required. The output object for the duplicate rule. This value is the same as the value of the matchRuleSObjectType field in [DuplicateRuleMatchRule](#DuplicateRuleMatchRule). Any duplicate rules that this object has are ignored when the DuplicateRule API uses the ObjectMapping. |

## ObjectMappingField

A field name in the input object of the DuplicateRule, and the corresponding field name in the output object.

| Field Name | Field Type | Description |
| --- | --- | --- |
| inputField | string | Required. Field in the object specified by the inputObject field in [ObjectMapping](#ObjectMapping). This field is mapped to the field in outputField, which is assumed to be a field in the object specified by the outputObject field in [ObjectMapping](#ObjectMapping). |
| outputField | string | Required. Field in the object specified by the outputObject field in [ObjectMapping](#ObjectMapping). The field is mapped to the field name in inputField, which is assumed to be a field in the object specified by the inputObject in [ObjectMapping](#ObjectMapping). |

## Declarative Metadata Sample Definition

The following is an example of a DuplicateRule component.

<?xml version="1.0" encoding="UTF-8"?>
<DuplicateRule xmlns="http://soap.sforce.com/2006/04/metadata" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <actionOnInsert\>Allow</actionOnInsert\>
    <actionOnUpdate\>Allow</actionOnUpdate\>
    <alertText\>You are creating a duplicate record. Use an existing record instead.</alertText\>
    <description\>Detects a contact that duplicates a Lead</description\>
    <duplicateRuleFilter\>
        <booleanFilter xsi:nil="true"/>
        <duplicateRuleFilterItems\>
            <field\>Username</field\>
            <operation\>equals</operation\>
            <value\>user@example.com</value\>
            <sortOrder\>1</sortOrder\>
            <table\>User</table\>
        </duplicateRuleFilterItems\>
    </duplicateRuleFilter\>
    <duplicateRuleMatchRules\>
        <matchRuleSObjectType\>Lead</matchRuleSObjectType\>
        <matchingRule\>ContactToLeadDuplicate\_matching\_rule</matchingRule\>
        <objectMapping\>
            <inputObject\>Contact</inputObject\>
            <mappingFields\>
                <inputField\>FirstName</inputField\>
                <outputField\>FirstName</outputField\>
            </mappingFields\>
            <mappingFields\>
                <inputField\>LastName</inputField\>
                <outputField\>LastName</outputField\>
            </mappingFields\>
            <outputObject\>Lead</outputObject\>
        </objectMapping\>
    </duplicateRuleMatchRules\>
    <isActive\>true</isActive\>
    <masterLabel\>ContactToLeadDuplicate</masterLabel\>
    <operationsOnInsert\>Alert</operationsOnInsert\>
    <operationsOnInsert\>Report</operationsOnInsert\>
    <operationsOnUpdate\>Alert</operationsOnUpdate\>
    <operationsOnUpdate\>Report</operationsOnUpdate\>
    <securityOption\>EnforceSharingRules</securityOption\>
    <sortOrder\>1</sortOrder\>
</DuplicateRule\>

The following is an example package.xml that references the previous definition.

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types\>
        <members\>ContactToLeadDuplicate</members\>
        <name\>DuplicateRule</name\>
    </types\>
    <version\>38.0</version\>
</Package\>

## Wildcard Support in the Manifest File

This metadata type supports the wildcard character \* (asterisk) in the package.xml manifest file. For information about using the manifest file, see [Deploying and Retrieving Metadata with the Zip File](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/file_based_zip_file.htm "The deploy() and retrieve() calls are used to deploy and retrieve a .zip file. Within the .zip file is a project manifest (package.xml) that lists what to retrieve or deploy, and one or more XML components that are organized into folders.").