Score person duplicate candidates

POST

https://api.aventure.vc/v1/people/duplicate-check/candidates

POST

/v1/people/duplicate-check/candidates

$ curl -X POST "https://api.aventure.vc/v1/people/duplicate-check/candidates?includePrivate=false&page=0&size=10" \
>      -H "X-Client-Secret: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d '{}'

1 {
2   "content": [
3     {
4       "id": "string",
5       "reason": [
6         "string"
7       ],
8       "score": 1,
9       "externalId": "string",
10       "name": "string",
11       "operatingStatus": "string",
12       "publicPath": "string",
13       "slug": "aventure-vc",
14       "typeRecord": "Company"
15     }
16   ],
17   "empty": true,
18   "first": true,
19   "last": true,
20   "number": 1,
21   "numberOfElements": 1,
22   "pageable": {
23     "offset": 1,
24     "pageNumber": 1,
25     "pageSize": 1,
26     "paged": true,
27     "sort": {
28       "empty": true,
29       "sorted": true,
30       "unsorted": true
31     },
32     "unpaged": true
33   },
34   "size": 1,
35   "sort": {
36     "empty": true,
37     "sorted": true,
38     "unsorted": true
39   },
40   "totalElements": 1,
41   "totalPages": 1
42 }

Return scored duplicate candidates for people queries. Results are ordered by match score; custom sorting is not supported. Exact same-name results after excludeId review are human identity review signals, not automatic merge proof.

Authentication

X-Client-Secretstring

Client secret for read-only service-to-service access (no writes)

Query parameters

pageintegerOptional

Zero-based page index (0..N)

sizeintegerOptional

The size of the page to be returned; duplicate-check default 10, maximum 100.

sortlist of stringsOptional

Sorting is not supported

includePrivatebooleanOptional

Privileged read scope for admin callers. Bypasses the public visibility filter so hidden, unverified, and not-yet-published records are returned instead of being silently dropped. Defaults to private for admin API key or ROLE_ADMIN callers; client-secret/client-read callers stay public.

Request

This endpoint expects an object.

excludeIdstring or nullOptionalformat: "uuid"

Current person id to omit from post-bootstrap duplicate audits while same-name candidates are reviewed.

locationstring or nullOptional

Location

nameAnystring or nullOptional

Loose name match

nameFullstring or nullOptional

Full name

qwen4bFp16Embeddinglist of float or nullOptional

Embedding vector pinned to qwen-4b-fp16 (Qwen3-Embedding-4B-f16.gguf) from https://huggingface.co/Qwen/Qwen3-Embedding-4B-GGUF?show_file_info=Qwen3-Embedding-4B-f16.gguf; only this fp16 model is accepted and exactly 2560 floats are required

slugstring or nullOptional

URL-safe identifier

urlstring or nullOptional

Profile URL

urlCandidatelist of objectsOptional

Additional URL candidates to match

urlDomainstring or nullOptional

URL domain match

urlMatchModeenum or nullOptional

URL match mode

urlStrictnessenum or nullOptional

Optional URL match strictness. Omit for strict matching. Send loose or any only when the caller intentionally widens URL matching.

urlTypeenum or nullOptional

URL type

Response

contentlist of objectsOptional

emptybooleanOptional

firstbooleanOptional

lastbooleanOptional

numberintegerOptional

numberOfElementsintegerOptional

pageableobjectOptional

sizeintegerOptional

sortobjectOptional

totalElementslongOptional

totalPagesintegerOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

406

Not Acceptable Error

409

Conflict Error

415

Unsupported Media Type Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error