Create an identity

Creates a stub identity record before any verification session exists. The identity will be populated automatically when a session with a matching external_ref completes verification.

Returns 409 Conflict if an identity with the given external_ref already exists.

Creates a stub identity record before any verification session exists. The identity will be populated automatically when a session with a matching external_ref completes verification.

Returns 409 Conflict if an identity with the given external_ref already exists.

Authentication

X-API-Keystring

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

Request

This endpoint expects an object.

external_refstringRequired

Your system's unique identifier for this person.

upsertbooleanOptionalDefaults to false

When true, returns existing identity if one exists for this external_ref (200) instead of returning 409.

Response

Existing identity returned (when upsert is true).

idstring

external_refstring

statusstring

is_sandboxboolean

created_atdatetime

upsertedboolean

Errors

401

Unauthorized Error

409

Conflict Error

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

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

Response key casing. Defaults to snake.

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

This endpoint expects an object.

Your system's unique identifier for this person.

When true, returns existing identity if one exists for this external_ref (200) instead of returning 409.

Existing identity returned (when upsert is true).

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

1	{
2	"id": "idn_abc123",
3	"external_ref": "string",
4	"status": "string",
5	"is_sandbox": true,
6	"created_at": "2024-01-15T09:30:00Z",
7	"upserted": true
8	}

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

1	{
2	"id": "idn_abc123",
3	"external_ref": "string",
4	"status": "string",
5	"is_sandbox": true,
6	"created_at": "2024-01-15T09:30:00Z",
7	"upserted": true
8	}

Create an identity

Authentication

Headers

Request

Response

Errors

Authentication

Headers

Request

Response

Errors