Merge identities

POST

https://devapi.withverifa.com/api/v1/identities/merge

POST

/api/v1/identities/merge

$ curl -X POST https://devapi.withverifa.com/api/v1/identities/merge \
>      -H "X-API-Key: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "primary_identity_id": "idn_abc123",
>   "secondary_identity_id": "idn_def456"
> }'

1 {
2   "primary": {
3     "id": "idn_abc123",
4     "status": "active",
5     "session_count": 5,
6     "is_sandbox": false,
7     "created_at": "2023-10-01T08:00:00Z",
8     "external_ref": "ext_ref_789",
9     "latest_session_id": "sess_987654321",
10     "latest_result_id": "res_123456789",
11     "latest_session_snapshot": {
12       "result_id": "res_123456789",
13       "session_id": "sess_987654321",
14       "status": "completed",
15       "face_match_passed": true,
16       "face_match_score": 0.92,
17       "age_check_passed": true,
18       "extracted_age": 34,
19       "rejection_reason": "None",
20       "rejection_reason_code": "other",
21       "check_results": {},
22       "reviewed_by": "verifier_jdoe",
23       "reviewed_at": "2024-01-15T09:30:00Z",
24       "created_at": "2024-01-15T09:30:00Z"
25     },
26     "country": "US",
27     "extracted_data": {
28       "first_name": "Jane",
29       "last_name": "Doe",
30       "date_of_birth": "1990-05-20",
31       "address": {
32         "line1": "123 Maple Street",
33         "line2": "Apt 4B",
34         "city": "Springfield",
35         "state": "IL",
36         "zip": "62704"
37       },
38       "document_number": "D1234567",
39       "nationality": "US",
40       "gender": "female",
41       "ssn": "123-45-6789",
42       "document_type": "drivers_license",
43       "document_expiration_date": "2028-05-20",
44       "document_issuing_state": "IL"
45     },
46     "first_verified_at": "2023-11-10T14:00:00Z",
47     "last_verified_at": "2024-01-15T09:30:00Z",
48     "archived_at": "2024-01-15T09:30:00Z",
49     "identity_type_id": "type_001",
50     "custom_fields": {},
51     "tags": [
52       "vip",
53       "trusted"
54     ],
55     "updated_at": "2024-01-15T09:30:00Z"
56   },
57   "secondary": {
58     "id": "idn_def456",
59     "status": "merged"
60   },
61   "transfer_summary": {
62     "sessions": true,
63     "screening_checks": true,
64     "face_embeddings": true,
65     "ip_links": true,
66     "device_links": true
67   },
68   "redacted_secondary": true,
69   "reason": "Duplicate identity merge after manual review"
70 }

Merges two identities into one. The secondary identity is folded into the primary. Per-object-type transfer toggles control which linked data is re-pointed. Tags are always merged.

Sessions linked to the secondary are re-pointed to the primary
Session counts are combined (when sessions are transferred)
Screening checks, face embeddings, IP/device links optionally transferred
Tags are merged and deduplicated
The secondary identity is marked as merged (or redacted if requested)

Both identities must belong to the same organization and environment. Redacted or already-merged identities cannot be used as the secondary.

Merges two identities into one. The secondary identity is folded into the primary. Per-object-type transfer toggles control which linked data is re-pointed. Tags are always merged. - Sessions linked to the secondary are re-pointed to the primary - Session counts are combined (when sessions are transferred) - Screening checks, face embeddings, IP/device links optionally transferred - Tags are merged and deduplicated - The secondary identity is marked as `merged` (or `redacted` if requested) Both identities must belong to the same organization and environment. Redacted or already-merged identities cannot be used as the secondary.

Authentication

X-API-Keystring

Organization API key. Keys are prefixed with vk_live_ (production) or vk_sandbox_ (sandbox).

Request

This endpoint expects an object.

primary_identity_idstringRequired

The identity to keep.

secondary_identity_idstringRequired

The identity to merge into the primary.

transferobjectOptional

Per-object-type toggles for what to transfer. All default to true.

redact_secondarybooleanOptionalDefaults to false

If true, redact the secondary identity's PII after merge.

reasonstring or nullOptional

Optional note explaining why the merge was performed.

Response

Merge result.

primaryobject

secondaryobject

transfer_summaryobject

Which object types were transferred.

redacted_secondaryboolean

reasonstring or null

Errors

401

Unauthorized Error

404

Not Found Error

422

Unprocessable Entity Error

Authentication

Headers

Request

Response

Errors