API v1
v1
View as Markdown

Preview a merge

GET /api/v1/vaults/{vault}/contacts/{contact}/merge/{other}

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.

vault uuid Required

The id of the vault the contacts live in. A path that is not a uuid answers 404 without a query being run.

contact uuid Required

The contact that survives. Everything the other holds comes to it.

other uuid Required

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.

data object

The preview.

data.type string

Always contact_merge_preview.

data.attributes object

Everything the preview reports.

data.attributes.kept object

The surviving contact.

data.attributes.kept.uuid string

Its id.

data.attributes.kept.name string

What it is called.

data.attributes.other object

The contact that would be absorbed.

data.attributes.other.uuid string

Its id.

data.attributes.other.name string

What it is called.

data.attributes.conflicts array

Every place the two disagree. Each one has to be decided before the merge will run.

data.attributes.conflicts[] object

One disagreement.

data.attributes.conflicts[].field_key string

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.

data.attributes.conflicts[].field_id integer

The field, null for the picture and for the name shown.

data.attributes.conflicts[].label string

What the field is called on the page.

data.attributes.conflicts[].row integer

The repeater entry, null for a plain difference.

data.attributes.conflicts[].kept_value string

What the surviving contact holds.

data.attributes.conflicts[].other_value string

What the other one holds.

data.attributes.moves array

How much of each kind of thing would come over. A kind with nothing to move is left out.

data.attributes.moves[] object

One kind of thing.

data.attributes.moves[].kind string

One of name_representation, field_value, field_value_row, reminder, share_link, group_membership or relation_pointer.

data.attributes.moves[].count integer

How many of them.

data.attributes.collisions array

Repeater entries the merge would place identically twice. Each one has to be decided too. Empty when there are none.

data.attributes.set_aside array

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.

data.attributes.folds array

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.

data.attributes.folds[] object

One group whose two memberships become one.

data.attributes.folds[].group string

The id of the group.

data.attributes.folds[].name string

What the group is called.

data.attributes.fingerprint string

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.

GET
curl https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/contacts/c4a1f7b2-8e36-4d59-b0a7-2f5c9d81e364/merge/7b2e9034-5c18-4af6-9d21-0e83b6c47a5f \
-H "Authorization: Bearer $MONICA_TOKEN"
const response = await fetch('https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/contacts/c4a1f7b2-8e36-4d59-b0a7-2f5c9d81e364/merge/7b2e9034-5c18-4af6-9d21-0e83b6c47a5f', {
headers: { Authorization: `Bearer ${token}` },
})
const data = await response.json()
$response = Http::withToken($token)->get('https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/contacts/c4a1f7b2-8e36-4d59-b0a7-2f5c9d81e364/merge/7b2e9034-5c18-4af6-9d21-0e83b6c47a5f');
Response 200
{
"data": {
"type": "contact_merge_preview",
"attributes": {
"kept": {
"uuid": "c4a1f7b2-8e36-4d59-b0a7-2f5c9d81e364",
"name": "Jim Halpert"
},
"other": {
"uuid": "7b2e9034-5c18-4af6-9d21-0e83b6c47a5f",
"name": "Jimmy Halpert"
},
"conflicts": [
{
"field_key": "email",
"field_id": 12,
"label": "Email",
"row": null,
"kept_value": "[email protected]",
"other_value": "[email protected]"
}
],
"moves": [
{
"kind": "field_value",
"count": 1
}
],
"collisions": [],
"set_aside": [],
"folds": [
{
"group": "0199a2b4-7c1d-7e3f-9a40-5b6c7d8e9f01",
"name": "Halpert household"
}
],
"fingerprint": "5f2c9d1b7a34e806c5f19d2b48a7361ce0947fb52d8a1c6e3947b0d85f2a1c63"
}
}
}

Keys act as you, with exactly the access you have. Make one per integration so you can revoke it alone.