Skip to navigation
Identity verification APIEntities

Update part of an entity

Changes only the fields you send. An absent key is left alone and null clears a nullable field. externalUserId and type cannot be changed, and unknown keys are rejected.

On an entity verified by Toden, fullName, dateOfBirth, nationality, idType, idNumber and kycProvenance are locked; a request touching any of them is refused and names the fields. Changing the verified document on an externally verified entity runs identity resolution again.

Side effects: when at least one field changed, the entity.updated webhook fires with the names of the changed fields (never their values) and the call is recorded in your audit log. A changed wallet set queues wallet screening again.

Error codes

errorStatusMeaning
invalid_request400The body failed validation. details carries the field-level breakdown.
field_not_editable400The request tried to change identity facts on an entity verified by Toden. fields lists them.
entity_not_found404No live entity has this reference in this organisation and environment.
secret_key_required403A publishable key was used. This API accepts secret keys only.
environment_mismatch403The key belongs to an environment this host does not serve.
rate_limited429The request rate limit for this key was reached. Retry after a short wait.
rate_limit_store_unavailable503Rate limiting is temporarily unavailable. Retry shortly.

A missing or unknown key returns 401 with a plain sentence in error rather than a code.

Requires a secret (sk_) key. A publishable key receives 403 secret_key_required.

Authentication

AuthorizationBearer
Send the API key as a Bearer token. Each operation states whether a publishable key is enough or a secret key is required.

Path parameters

externalUserIdstringRequired
Your own stable reference for the person or business, as sent when the entity was registered.

Request

This endpoint expects an object.
metadatamap from strings to anyOptional
Your own correlation fields for the entity. Sending it replaces the stored object. At most 16 KiB of JSON, four levels deep, 100 keys in total, 50 keys per object, 20 items per array, keys up to 64 characters and strings up to 1,000 characters.
kycSourcestring or nullOptional<=200 characters
A label for where the external verification came from, such as the name of your previous provider.
kycProvenanceenumOptional

Move the entity between unverified and externally verified. EXTERNAL_VERIFIED requires a non-empty kycSource in the same request.

Allowed values:
profileobjectOptional

The profile fields to change. An absent key is left alone and null clears a nullable field. Unknown keys are rejected.

Response

Success
entityIdstring
The Toden identifier of the entity.
externalUserIdstring
Your reference, echoed back.
identityIdstring or null

The identifier of the shared identity the entity is linked to, or null when it has not been resolved to one.

changedFieldslist of strings
The names of the fields that actually changed. Empty when the request changed nothing.
screeningobject or null

Set only when the wallet set changed and wallet screening was queued again; otherwise null.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
503
Service Unavailable Error