merge()

Syntax

MergeResult[]= connection.merge(MergeRequest[] mergeRequests);

Usage

Use this call to merge records of the same object type into one of the records, deleting the others, and re-parenting any related records. Each merge operation is within one transaction. A batch merge has multiple transactions, one for each element in the batch.

The only supported object types are Lead, Contact and Account.

The masterRecord field indicates which of the records is the master record that the others are merged into. You can use queryAll() to view records that have been deleted during a merge.

This call requires that you decide prior to the merge call if there are any field values from the non-master record(s) that should supersede the values in the master record. If so, the field names and their new values should be set in the masterRecord of the MergeRequest, similar to a call to update.

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 is the same limit as the Salesforce user interface. If you have more than three records to merge, use the same master record in each request to avoid errors.
External ID fields cannot be used with merge().

To find all records that have been merged since a given point in time, you can use queryAll() with a SELECT statement similar to the following:

SELECT Id FROM Contact WHERE isDeleted=true and masterRecordId != null 
   AND SystemModstamp > 2006-01-01T23:01:01+01:00

It is a recommended best practice to narrow your result set to the most relevant records by filtering on SystemModstamp.

Note

Starting with API version 15.0, if you specify a value for a field that contains a string, and the value is too big for the field, the call fails and an error is returned. In previous versions of the API the value was truncated and the call succeeded. If you wish to keep the old behavior with versions 15.0 and later, use the AllowFieldTruncationHeader SOAP header.

Sample Code—Java

This Java code merges a duplicate account into a master account. The note associated with the duplicate account is associated with the master account after the merge.

public String[] mergeRecords() {
  String[] result = new String[1];
  try {
    Account[] accounts = new Account[2];
    Account masterAccount = new Account();
    masterAccount.setName("MasterAccount");
    masterAccount.setDescription(
        "The Account record to merge with."
    );
    accounts[0] = masterAccount;
    Account accountToMerge = new Account();
    accountToMerge.setName("AccountToMerge");
    accountToMerge.setDescription(
        "The Account record to merge MasterAccount with."
    );
    accounts[1] = accountToMerge;
    SaveResult[] saveResults = connection.create(accounts);
    result[0] = saveResults[0].getId();
    masterAccount.setId(result[0]);
    // Attach a note, which will get re-parented 
    
    Note note = new Note();
    note.setParentId(result[0]);
    note.setTitle("Merged Notes");
    note.setBody("This note will be moved to the " + 
        "MasterAccount during merge"
    );
    SaveResult[] sRes = connection.create(new SObject[] {note});
    if ( sRes[0].isSuccess()) {
      System.out.println("Created Note record.");
    } else {
      Error[] errors = sRes[0].getErrors();
      System.out.println("Could not create Note record: " + 
          errors[0].getMessage());
    }
    MergeRequest mReq = new MergeRequest();
    masterAccount.setDescription("Was merged");
    mReq.setMasterRecord(masterAccount);
    mReq.setRecordToMergeIds(
        new String[] { saveResults[1].getId() }
    );
    MergeResult mRes = 
        connection.merge(new MergeRequest[] {mReq})[0];
    System.out.println("Merged " + mRes.isSuccess() + " got " + 
        mRes.getUpdatedRelatedIds().length + 
        " updated child records");
  } catch (ConnectionException ce) {
    ce.printStackTrace();
  }
  return result;
}

Sample Code—C#

This C# code merges a duplicate account into a master account. The note associated with the duplicate account is associated with the master account after the merge.

private void mergeSample()
 {
     try
     {
         Account masterAccount = new Account();
         masterAccount.Name = "MasterAccount";
         SaveResult sr = binding.create(new sObject[] { masterAccount })[0];
         masterAccount.Id = sr.id;
         masterAccount.Description = "Old description";
 
         Account accountToMerge = new Account();
         accountToMerge.Name = "AccountToMerge";
         accountToMerge.Description = "Duplicte account";
         SaveResult accountToMergeSaveResult = binding.create(new sObject[] 
              { accountToMerge })[0];
 
         // Attach a note, which will get re-parented 
    
         Note note = new Note();
         note.ParentId = accountToMergeSaveResult.id;
         note.Body = "This note will be moved to the MasterAccount during merge";
         binding.create(new sObject[] { note });
 
         MergeRequest mr = new MergeRequest();
         // Perform an update on the master record as part of the merge: 
    
         masterAccount.Description = "Was merged";
         mr.masterRecord = masterAccount;
         mr.recordToMergeIds = new String[] { accountToMergeSaveResult.id };
         MergeResult result = binding.merge(new MergeRequest[] { mr })[0];
         Console.WriteLine("Merged " + result.success + " got " + result.ToString() 
              + " updated child records");
     }
            catch (Exception ex)
     {
                Console.WriteLine(ex.ToString());
     }
 }

Arguments

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

Name	Type	Description
masterRecord	sObject	Required. Must provide the ID of the object that other records will be merged into. Optionally, provide the fields to be updated and their values.
recordToMergeIds	ID[]	Required. Minimum of one, maximum of two. The other record or records to be merged into the master record.

Response

MergeResult[]

Faults

InvalidSObjectFault

UnexpectedErrorFault

InvalidIdFault