Preview identity merge

POST

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

POST

/api/v1/identities/merge-preview

$ curl -X POST https://devapi.withverifa.com/api/v1/identities/merge-preview \
>      -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": "verified",
5     "session_count": 5,
6     "is_sandbox": false,
7     "created_at": "2023-10-01T08:00:00Z",
8     "external_ref": "EXT-2024-0001",
9     "latest_session_id": "sess_789xyz",
10     "latest_result_id": "res_456abc",
11     "latest_session_snapshot": {
12       "result_id": "res_456abc",
13       "session_id": "sess_789xyz",
14       "status": "approved",
15       "face_match_passed": true,
16       "face_match_score": 0.95,
17       "age_check_passed": true,
18       "extracted_age": 34,
19       "rejection_reason": "",
20       "rejection_reason_code": "",
21       "check_results": {},
22       "reviewed_by": "agent_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": "Alice",
29       "last_name": "Johnson",
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-02-01T00:00:00Z",
49     "identity_type_id": "type_driver_license",
50     "custom_fields": {},
51     "tags": [
52       "trusted",
53       "vip"
54     ],
55     "updated_at": "2024-01-15T09:30:00Z"
56   },
57   "secondary": {
58     "id": "idn_def456",
59     "status": "pending_review",
60     "session_count": 3,
61     "is_sandbox": false,
62     "created_at": "2023-11-15T09:00:00Z",
63     "external_ref": "EXT-2024-0002",
64     "latest_session_id": "sess_123abc",
65     "latest_result_id": "res_789def",
66     "latest_session_snapshot": {
67       "result_id": "res_789def",
68       "session_id": "sess_123abc",
69       "status": "review_required",
70       "face_match_passed": false,
71       "face_match_score": 0.65,
72       "age_check_passed": true,
73       "extracted_age": 33,
74       "rejection_reason": "Face mismatch detected",
75       "rejection_reason_code": "face_mismatch",
76       "check_results": {},
77       "reviewed_by": "agent_smith",
78       "reviewed_at": "2024-01-10T11:15:00Z",
79       "created_at": "2024-01-10T11:00:00Z"
80     },
81     "country": "US",
82     "extracted_data": {
83       "first_name": "Alicia",
84       "last_name": "Johnston",
85       "date_of_birth": "1991-06-15",
86       "address": {
87         "line1": "456 Oak Avenue",
88         "line2": "",
89         "city": "Springfield",
90         "state": "IL",
91         "zip": "62705"
92       },
93       "document_number": "P9876543",
94       "nationality": "US",
95       "gender": "female",
96       "ssn": "987-65-4321",
97       "document_type": "passport",
98       "document_expiration_date": "2029-06-15",
99       "document_issuing_state": "US"
100     },
101     "first_verified_at": "2023-12-01T10:00:00Z",
102     "last_verified_at": "2024-01-10T11:15:00Z",
103     "archived_at": "2024-02-05T00:00:00Z",
104     "identity_type_id": "type_passport",
105     "custom_fields": {},
106     "tags": [
107       "new_user",
108       "needs_review"
109     ],
110     "updated_at": "2024-01-10T11:15:00Z"
111   },
112   "transfer_counts": {
113     "sessions": 3,
114     "screening_checks": 2,
115     "face_embeddings": 1,
116     "ip_links": 1,
117     "device_links": 0
118   },
119   "screening_impact": {
120     "current_primary_status": "verified",
121     "current_secondary_status": "pending_review",
122     "post_merge_status": "verified",
123     "status_would_change": false
124   },
125   "tags_combined": [
126     "trusted",
127     "vip",
128     "new_user",
129     "needs_review"
130   ],
131   "primary_extracted_data": {},
132   "secondary_extracted_data": {}
133 }

Returns a read-only preview of what merging two identities would do. Includes transfer counts for each object type, screening status impact, combined tags, and decrypted PII for both identities for side-by-side comparison. No data is modified.

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 that would be kept.

secondary_identity_idstringRequired

The identity that would be merged in.

Response

Merge preview.

primaryobject

secondaryobject

transfer_countsobject

Number of objects that would be transferred from secondary to primary.

screening_impactobject

tags_combinedlist of strings

primary_extracted_dataobject

Decrypted PII fields for the primary identity.

secondary_extracted_dataobject

Decrypted PII fields for the secondary identity.

Errors

401

Unauthorized Error

422

Unprocessable Entity Error

Authentication

Headers

Request

Response

Errors