Create an identity relationship

POST

https://api.withverifa.com/api/v1/identities/:identity_id/relationships

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.

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.

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

$	curl -X POST https://api.withverifa.com/api/v1/identities/identity_id/relationships \
>	-H "X-API-Key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"related_identity_id": "idn_def456"
>	}'

1	{
2	"id": "idrel_abc123",
3	"source_identity_id": "idn_abc123",
4	"related_identity_id": "idn_def456",
5	"relationship_type": "user_linked",
6	"metadata": {}
7	}