merge()

Combines up to 3 records of the same type into 1 record. The input is an array of MergeRequest elements, each of which specifies the records to combine. The output is a MergeResult object that contains information about the result of the merge.

Syntax

Usage

Use merge() to combine records of the same object type into one of the records, known as the master record. merge() deletes the other records, known as the victim records. If a victim record has related records, merge() makes the master record the new parent of the related records.

Rules and Guidelines

Values from non-master records

Before you call merge(), decide if you want field values in the non-master records to supersede the master record values. If you do, set the field names and values in the record identified by the masterRecord of the MergeRequest.

Successive merges

Because merge() handles each MergeResult element in the input argument as a separate transaction, you can successively merge several records into the same master record.

To perform successive merges, call merge() with an array of MergeResult elements. For each MergeResult element, set:

• masterRecord to the master record ID.
• Each element in the recordToMergeIds array to the ID of a record you want to combine into the master.

Deleted records

Use queryAll() to view records that have been deleted during a merge.

List merged records

To find all records that have been merged since a given point in time, call queryAll() with a SELECT statement. For example:

Supported Object Types

The supported object types are Lead, Contact, Account, and Person Account. You can only merge objects of the same type. For example, Leads can be merged only with Leads.

Account Hierarchies

When you merge accounts that are part of an account hierarchy, merge() tries to set the victims’ child records as children of the master. If this action causes a cyclical relationship, merge() returns an error.

Contacts Reports To relationships

When you merge contacts that have a value for the ReportsToId field, merge() tries to add the victims’ ReportsToId value to the master. If this action causes a cyclical relationship, merge()reports an error.

Contacts and portal users

When you want to merge a contact victim record that has an associated portal user, set AdditionalInformationMap for victim record’s MergeRequest element. You can only merge 1 victim with a portal user into the master. In Salesforce Classic, you can’t merge person accounts that are enabled to use a Customer Portal.

Considerations

The following limits apply to any merge request:

• Up to 200 merge requests can be made in a single SOAP call.
• Up to three records can be merged in a single request, including the master record. This limit is the same as the limit enforced by the Salesforce user interface. To merge more than 3 records, do a successive merge.
• External ID fields cannot be used with merge().

Redundant relationships

You can’t merge accounts or person accounts that are related to the same contact. Remove redundant account-contact relationships before you try to merge accounts.

Sample Code—Java

This sample merges a victim account with a master account. It creates 2 accounts and attaches a note to the victim. After the merge, the code prints the ID of the victim account and the number of child records updated. In this example, the number of updated records is one, because the note of the merged account is moved to the master.

Sample Code—C#

This sample merges a victim account with a master account. It creates 2 accounts and attaches a note to the victim. After the merge, the code prints the ID of the victim account and the number of child records updated. In this example, the number of updated records is one, because the note of the merged account is moved to the master.

Arguments

This call accepts an array of MergeRequest objects. A MergeRequest object contains the following properties.

Response

MergeResult[]

Faults

InvalidSObjectFault

UnexpectedErrorFault

InvalidIdFault