Skip to navigation
Identity verification APIEntities

Delete an entity

Soft-deletes the entity. It leaves every read on this API and the dashboard, and its ongoing screening is paused with all history kept. Its verifications and the shared identity it was linked to are untouched. There is no restore endpoint, but registering the same externalUserId again brings the entity back.

Side effects: the entity.deleted webhook fires and the call is recorded in your audit log with the reason you gave. Nothing is refunded.

Error codes

errorStatusMeaning
invalid_request400The reason is longer than 500 characters.
entity_not_found404No live entity has this reference, or it was already deleted.
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.
reasonstringOptional<=500 characters
Why the entity is being deleted, kept in your audit log.

Response

Success
entityIdstring
The Toden identifier of the entity.
externalUserIdstring
Your reference, echoed back.
deletedboolean
Always true.
deletedAtdatetime
When the entity was deleted.
screeningPausedboolean
True when ongoing screening for the entity was paused by the deletion.

Errors

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