Preview a merge
Work out what merging one contact into another would do, without doing any of it.
Ask this first. Whatever it reports is what the merge is then allowed to write: a decision it never asked about is refused, and a difference it did ask about and you left undecided is refused too.
A difference is a place where both contacts hold a value and the two do not agree. A value only one of them holds is not a difference, it simply comes over.
Keep the fingerprint. Hand it back when you merge, and if either contact changed in between the merge is refused rather than applied to a state nobody looked at.
The two contacts have to be in the same vault. Merging a contact with itself, and absorbing the contact that represents you, are both refused.
This endpoint also answers QUERY, with the same parameters sent in the request body. How QUERY works.
Path parameters
Sent as JSON. Anything not listed here is ignored.
The id of the vault the contacts live in. A path that is not a uuid answers 404 without a query being run.
The contact that survives. Everything the other holds comes to it.
The contact that is absorbed. It is kept, soft deleted, and its address lands on the survivor.
Returns
What the merge would do. A contact belonging to somebody else, or reached through the wrong vault, answers 404. The same contact twice, or the contact representing you as the one absorbed, answers 422. While an import writes into the vault, or rolls back what it wrote, the preview answers 409.
The preview.
Always contact_merge_preview.
Everything the preview reports.
The surviving contact.
Its id.
What it is called.
The contact that would be absorbed.
Its id.
What it is called.
Every place the two disagree. Each one has to be decided before the merge will run.
One disagreement.
The key of the field, @avatar for the picture, or @display_name for the name shown. No field key starts with @. The name shown may be left undecided, and the surviving contact then keeps its own.
The field, null for the picture and for the name shown.
What the field is called on the page.
The repeater entry, null for a plain difference.
What the surviving contact holds.
What the other one holds.
How much of each kind of thing would come over. A kind with nothing to move is left out.
One kind of thing.
One of name_representation, field_value, field_value_row, reminder, share_link, group_membership or relation_pointer.
How many of them.
Repeater entries the merge would place identically twice. Each one has to be decided too. Empty when there are none.
Answers with no matching question on the surviving structure. They are kept out of the way rather than thrown away. Empty when there are none.
Groups both contacts are current members of. The two memberships become one, from the earlier join date, with the surviving contact's role unless it has none. Empty when there are none.
One group whose two memberships become one.
The id of the group.
What the group is called.
What the preview was built on. Hand it back when you merge and the merge is refused if either contact changed in between.
Rate limit
Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in X-RateLimit-Remaining.
Keys act as you, with exactly the access you have. Make one per integration so you can revoke it alone.