API v1
v1
View as Markdown

List possible duplicates

GET /api/v1/vaults/{vault}/duplicates

List the pairs of contacts in one of your vaults that look like the same person, strongest resemblance first.

Two signals put a pair on this list. Names that resemble each other, and an exact shared value in a field your structure marks as identifying, which is what catches a pair whose names do not resemble each other at all. The reasons say which fired.

The list is worked out on a queue, not while you are reading it. Creating or renaming a contact queues a look at that contact, and a nightly pass looks at every vault, which is what notices a template that has just gained an identifying field. So a pair created a second ago may not be here yet.

A pair somebody has ruled out is never in the list again. A vault with nothing doubled answers with an empty list rather than an error.

Nothing here merges anything. This says two records might be one person, and a person decides.

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.

Returns

A page of pairs, and how many there are in all. A vault belonging to somebody else answers 404.

data array

The pairs on this page. An empty list rather than an error when there are none.

data[] object

One pair.

data[].type string

Always contact_duplicate_candidate. 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.contact_id string

One of the two contacts.

data[].attributes.other_contact_id string

The other one.

data[].attributes.contact_name string

What the first one is called, so a list reads without a second request.

data[].attributes.other_contact_name string

What the second one is called.

data[].attributes.score integer

How strongly the two resemble each other, 0 to 100. It orders the list and says nothing about certainty.

data[].attributes.reasons array

One entry per signal that fired.

data[].attributes.reasons[] object

One signal.

data[].attributes.reasons[].kind string

Either name, when the two names resemble each other, or field, when the two share a value in a field the structure marks as identifying.

data[].attributes.reasons[].field_key string

The key of that field. Only on a field signal.

data[].attributes.reasons[].value string

The value the two share. Only on a field signal.

data[].attributes.dismissed_at integer

When somebody said these are two different people, null while the pair stands.

data[].attributes.computed_at integer

When detection last looked at this pair.

meta object

Where you are in the collection.

meta.page integer

The page this is, counting from 1.

meta.per_page integer

How many one page holds, which is the size that was asked for once it has been brought into the allowed range.

meta.total integer

How many pairs there are in all, not how many are on this page.

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/duplicates \
-H "Authorization: Bearer $MONICA_TOKEN"
const response = await fetch('https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/duplicates', {
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/duplicates');
Response 200
{
"data": [
{
"type": "contact_duplicate_candidate",
"id": "42",
"attributes": {
"contact_id": "c4a1f7b2-8e36-4d59-b0a7-2f5c9d81e364",
"other_contact_id": "7b2e9034-5c18-4af6-9d21-0e83b6c47a5f",
"contact_name": "Jim Halpert",
"other_contact_name": "Jimmy Halpert",
"score": 95,
"reasons": [
{
"kind": "field",
"field_key": "email",
"value": "[email protected]"
},
{
"kind": "name"
}
],
"dismissed_at": null,
"computed_at": 1757462400
}
}
],
"meta": {
"page": 1,
"per_page": 25,
"total": 1
}
}

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