API ReferenceIdentities

Update an identity

Updates fields on an existing identity. PII fields are re-encrypted and HMAC hashes are recomputed. Redacted identities cannot be updated.

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.
external_refstringOptional
New external reference for this identity.
first_namestringOptional

First name (PII, encrypted at rest).

last_namestringOptional

Last name (PII, encrypted at rest).

date_of_birthdateOptional

Date of birth as YYYY-MM-DD (PII, encrypted at rest).

address_line1stringOptional
Address line 1.
address_line2stringOptional
Address line 2.
citystringOptional
City.
statestringOptional
State or province.
zip_codestringOptional
Postal or ZIP code.
document_numberstringOptional

Document number (PII, encrypted at rest).

ssnstringOptional

Social Security Number (PII, encrypted at rest).

nationalitystringOptional

ISO 3166-1 alpha-2 nationality code.

genderstringOptional
Gender.
countrystringOptional

ISO 3166-1 alpha-2 country code.

emailstringOptional

Email address (PII, encrypted at rest).

phonestringOptional

Phone number (PII, encrypted at rest).

statusstringOptional
New status for the identity.

Response

Updated identity.
idstring
statusstring
session_countinteger
is_sandboxboolean
created_atdatetime
external_refstring or null
latest_session_idstring or null
latest_result_idstring or null
face_match_passedboolean or null
age_check_passedboolean or null
extracted_ageinteger or null
rejection_reasonstring or null
countrystring or null
extracted_dataobject

PII extracted from the identity document. Fields returned depend on your organization’s api_pii_fields configuration.

first_verified_atdatetime or null
last_verified_atdatetime or null
archived_atdatetime or null
identity_type_idstring or null
custom_fieldsmap from strings to any
tagslist of strings
updated_atdatetime

Errors

401
Unauthorized Error
404
Not Found Error
422
Unprocessable Entity Error