Merge contacts via API

We have external automations and tools for handling duplicate contacts. When an external automation or a human using external tools decides a contact should be merged, the automation/tool should be able to perform the merge using the API.

The only API option now is to update one contact with the needed fields from the other and delete the duplicate, which does not move associated records like notes, contact log, automation log, or custom objects. Some of these can be tediously reassigned or recreated via the API, but others like Contact Log cannot.

The only way to merge the contacts and preserve those associated records is to have a human open the duplicates tool on the web, select fields to match, select the contacts, and select the fields to merge. There is no way to link directly to the field selection page (step 3) or pre-fill it. If a duplicate contact was identified that doesn't have a matching high-cardinality field, for example the duplicate phone number is in sms_number on one contact and office_phone on the other, it is even more annoying to merge them manually.

As an example that I think would satisfy our need:

POST /objects/merge
{
  objectID: 0,
  kept[_unique]_id: "1234",
  condemned[_unique]_id: "5678",
  // fill selected empty fields in the kept record with condemned values
  combine_from_condemned: "*",
  // overwrite selected fields in kept record with condemned values
  overwrite_with_condemned: "contact_owner,f1111,f2222",
  // wishlist: if kept and condemned values for a field differ, save the condemned value in a different field
  shuffle_collisions: {
    // preserve unique email into custom "Other Email" field f3333
    email: "f3333",
    // preserve unique ph# into custom "Other Phone" field f4444
    sms_phone: "f4444";
    // preserve unique/colliding "Other Phone into office_phone
    f4444: "office_phone";
  },
  // otherwise, we can do that logic and provide explicit merged values
  other_values: {
    f5555: "Lorem ipsum dolor sit amet"
  }
}