# 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

- `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`.

## Request

```sh
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"
  }'
```

```javascript
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()
```

```php
$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`

```json
{
    "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
        }
    }
}
```
