API ReferenceIdentities

Create an identity relationship

Creates a bidirectional relationship between two identities. Accepts either a built-in user type or the name of an active custom relationship type defined via /relationship-types. System relationship types (same_document, same_name_dob, same_ssn, merged, etc.) cannot be created via the API.

Authentication

X-API-Keystring

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

Path parameters

identity_idstringRequired

Identity ID (idn_*) or external reference.

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.
related_identity_idstringRequired
The identity to link to.
relationship_typestringOptionalDefaults to user_linked

Built-in user type (user_linked, same_household, family_member, business_associate, authorized_representative, power_of_attorney, beneficial_owner, related_account) or the name of an active custom relationship type.

notestringOptional
Optional note explaining the reason for linking.
metadatamap from strings to anyOptional
Optional metadata to attach to the relationship.

Response

Relationship created.
idstring
source_identity_idstring
related_identity_idstring
relationship_typestring
metadataobject

Errors

401
Unauthorized Error
404
Not Found Error
422
Unprocessable Entity Error