For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
  • Getting Started
    • Introduction
    • How Verifa Works
    • Quickstart
    • Choosing an Integration Method
  • Use Cases
    • KYC Onboarding
    • Age Verification
    • AML Compliance
    • Fraud Prevention
    • Marketplace Trust & Safety
  • Core Concepts
    • Overview
    • Sessions
    • Verifications & Checks
    • Workflows
    • Identities
    • Cases
    • Screening & Reports
    • Lists
  • Integration Guides
    • Overview
    • JavaScript SDK
    • Web Capture Flow
    • API-Only Integration
    • Mobile SDK
    • Webhooks Guide
    • MCP Server
    • Migrating from Persona
  • API Details
    • Overview
    • Authentication
    • Pagination
    • Rate Limiting
    • Versioning
    • Errors
    • Webhooks
    • Idempotency
    • Key Inflection
    • Data Access
    • Data Retention
  • Tutorials
    • Creating Your First Verification Session
    • Creating a Workflow
    • Receiving Webhooks & Validating Signatures
    • Handling Webhook Events
    • Custom Document Types & AI Extraction
  • Best Practices
    • Testing
    • Preventing Duplicates
    • Fraud Signals
    • Changelog
  • API Reference
      • GETList identities
      • POSTCreate an identity
      • GETGet an identity
      • PATCHUpdate an identity
      • DELRedact an identity
      • GETExport identity data (GDPR Art. 15 DSAR)
      • POSTSearch identities
      • GETList identity sessions
      • GETGet identity audit log
      • POSTAdd a tag
      • POSTRemove a tag
      • POSTSet tags
      • POSTPreview identity merge
      • POSTMerge identities
      • POSTArchive an identity
      • POSTRestore an archived identity
      • POSTPause continuous monitoring for an identity
      • POSTResume continuous monitoring for an identity
      • POSTAdvanced identity search
      • GETGet custom field values
      • PATCHSet custom field values
      • GETList identity relationships
      • POSTCreate an identity relationship
      • DELDelete an identity relationship
      • GETQuery identity relationship graph
      • GETFind cross-session image similarity matches
      • GETGet monitored lists for an identity
      • POSTAdd lists to identity monitoring
      • PUTReplace monitored lists for an identity
API ReferenceIdentities

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.
Was this page helpful?
Previous

Archive an identity

Next
Built with

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

Headers

Verifa-VersiondateOptional

API version date string (e.g. 2026-02-01). If omitted, the version pinned to your API key is used.

Key-InflectionenumOptionalDefaults to snake

Response key casing. Defaults to snake.

Allowed values:
Idempotency-KeystringOptional<=255 characters

Unique key for idempotent requests. Cached for 24 hours. Sending the same key with different parameters returns 422.

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