API v1
v1
View as Markdown

Merge two contacts

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

Make two contacts one, keeping everything either of them held.

Everything attached to the absorbed contact comes over: values, repeater entries, files, the picture, reminders, shared links, and the relation fields other records pointed at it through.

Nothing is destroyed. The absorbed contact is soft deleted and keeps its own rows, so a value you chose not to bring over is still there. A value the survivor gave up is set aside rather than deleted, and so is a value whose field the surviving structure does not carry.

The state of the survivor is captured before anything is written, and what moved is recorded, so the whole thing can be undone.

Send one resolution for every difference and collision the preview reported, and none it did not. keep is kept or other for a difference, kept or both for a collision.

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.

fingerprint string Optional

What the preview was built on. Leave it out and the merge runs against whatever the two contacts hold now, which is only safe if nothing else is writing.

resolutions array Optional

One entry per difference and collision the preview reported. Leave it out only when the preview reported none.

resolutions[].field_key string Required

The key of the field the preview named.

resolutions[].row integer Optional

The repeater entry, for a collision. Null or absent for a plain difference.

resolutions[].keep string Required

kept or other for a difference. kept or both for a collision.

Returns

The record of the merge. A contact belonging to somebody else answers 404. A resolution the preview never reported, one left undecided, and absorbing the contact representing you each answer 422. A contact changed since the preview answers 409, and nothing is written. So does a merge asked for while an import writes into the vault or rolls back what it wrote.

data object

The merge.

data.type string

Always contact_merge. It names the kind of record, so a caller holding several kinds can tell them apart without looking at where they came from.

data.id string

The id of this record, as a string even when it reads as a number. It is what every endpoint naming this record takes.

data.attributes object

Everything the record holds.

data.attributes.kept_contact_id string

The contact that survived.

data.attributes.merged_contact_id string

The contact that was absorbed. It is soft deleted, not destroyed.

data.attributes.resolutions array

What was decided at every difference, exactly as it was sent.

data.attributes.resolutions[] object

One decision.

data.attributes.resolutions[].field_key string

The field it was about.

data.attributes.resolutions[].row integer

The repeater entry, null for a plain difference.

data.attributes.resolutions[].keep string

What was kept: kept, other or both.

data.attributes.moved array

What moved, row by row. It is what the undo replays backwards.

data.attributes.moved[] object

One thing that moved.

data.attributes.moved[].kind string

What happened, such as value_moved, row_moved, reminder_moved, value_detached or name_representation_moved.

data.attributes.moved[].id integer

The row it happened to.

data.attributes.moved[].from integer

The contact it came from, where the entry names one.

data.attributes.moved[].position integer

For a way of writing the name that came over, where it stood in the list of the contact it came from.

data.attributes.stands boolean

Whether the merge is still in force. False once it has been undone.

data.attributes.undone_at integer

When it was undone, null while it stands.

data.attributes.created_at integer

When the merge ran.

Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in X-RateLimit-Remaining.

POST
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 \
-X POST \
-H "Authorization: Bearer $MONICA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"fingerprint": "5f2c9d1b7a34e806c5f19d2b48a7361ce0947fb52d8a1c6e3947b0d85f2a1c63"
}'
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', {
method: 'POST',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
fingerprint: '5f2c9d1b7a34e806c5f19d2b48a7361ce0947fb52d8a1c6e3947b0d85f2a1c63',
}),
})
const data = await response.json()
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/contacts/c4a1f7b2-8e36-4d59-b0a7-2f5c9d81e364/merge/7b2e9034-5c18-4af6-9d21-0e83b6c47a5f', [
'fingerprint' => '5f2c9d1b7a34e806c5f19d2b48a7361ce0947fb52d8a1c6e3947b0d85f2a1c63',
]);
Response 201
{
"data": {
"type": "contact_merge",
"id": "e58c3a17-90d2-4b6e-8f14-7a3c05d9b2e8",
"attributes": {
"kept_contact_id": "c4a1f7b2-8e36-4d59-b0a7-2f5c9d81e364",
"merged_contact_id": "7b2e9034-5c18-4af6-9d21-0e83b6c47a5f",
"resolutions": [
{
"field_key": "email",
"row": null,
"keep": "kept"
}
],
"moved": [
{
"kind": "name_representation_moved",
"id": 64,
"from": 27,
"position": 2
},
{
"kind": "value_moved",
"id": 811,
"from": 27
}
],
"stands": true,
"undone_at": null,
"created_at": 1757548800
}
}
}

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