Skip to main content
DELETE

KYC and KYB support

Works for both User Verification (KYC) and Business Verification (KYB) sessions. The session_id is resolved against both session types; the same delete behavior applies to both. Biometric-template retention only applies to KYC sessions, because only KYC sessions carry a face embedding.

Behavior

  • The session is deleted with every verification attempt it holds, including results that a resubmission replaced: its decision, its extracted data, its associated feature records (ID verifications, registry checks, documents, AML, IP analysis, and so on), its reviews and activity log, and all of its stored files.
  • Deleting a Business Verification (KYB) session also deletes the verifications it created for its key people (KYC) and its corporate owners (KYB), recursively. The response reports how many in deleted_child_verifications. A verification it only links to, such as an existing approved KYC it reused, is not deleted.
  • E-signature data goes with it: the documents to sign and their original Word files, the signed PDFs, the evidence PDFs, the signature images and every field value. Their download paths return 404.
  • The session disappears from list and decision responses immediately, and media URLs issued before the call stop resolving.
  • Webhook deliveries still queued for the session, and their retries, are dropped.
  • Ongoing AML monitoring and KYB registry monitoring started by the deleted verifications stop.
  • Deletion is permanent and irreversible. There is no restore endpoint, so export anything you need, such as a decision PDF, before you call it.
  • The response is 200 OK, sent once the deletion has completed, with a JSON body that reports what happened to the session’s face biometric data. See Migration if your client still expects 204.

Data in a finalized regulatory report

If the session is part of a case with a finalized regulatory report, the request returns 409 and nothing is deleted. The response uses code: in_filed_report and names each report:
Delete each report with Delete Report, then repeat the deletion. Deleting the report does not delete the session; the session remains until you call this endpoint again.

Face biometric data: delete or retain

Every KYC session with a liveness selfie carries a face embedding that powers Face Search 1:N and duplicate detection. By default that embedding is deleted with the session (face_retention_policy: delete_with_session), so a person whose session you deleted can verify again without being flagged as a duplicate. Applications that need duplicate detection to survive session deletion can opt in to biometric-template retention. Didit then deletes the session and all of its data as usual, and keeps one separately managed, image-free face biometric template anchored to the session’s User.
A retained biometric template is biometric data. It is not anonymous, it is not transient, and it is not deleted with the session. It stays until its scheduled expiry, an earlier applicable-law deadline, User deletion, a privacy-erasure request, or an explicit purge. Only enable retention when your controller instruction and privacy notice cover it.
What a retained template does and does not contain: Retention is configured in three places, from broadest to most specific:
  1. Application policy in Business Console → App Settings → Data retention or through PATCH /v3/webhook/ (face_retention_policy, face_retention_days). See Data retention.
  2. Per-call override with retain_face_embeddings on this endpoint and on Batch Delete Sessions.
  3. Instruction class with deletion_instruction. A privacy_erasure instruction always wins: it purges every retained template for that User and never retains a new one.

Request body

All fields are optional. Omit the body to follow the application policy.

Response

The response confirms that Didit accepted and applied your deletion instruction. It is not an erasure certificate: keep the instruction_id in your own erasure log so you can correlate the audit trail later.

Retention duration and expiry

Every retained template has a finite expires_at. Didit sets it to the earliest of:
  1. face_retention_days from the request, or the application’s face_retention_days when the request omits it;
  2. the application’s general data-retention window, when one is configured;
  3. face_retention_deadline from the request, when provided.
A request that would retain a template without any finite duration is rejected with 400 and nothing is deleted. Retained templates cannot outlive the earliest applicable customer instruction, purpose end, configured expiry, data-subject erasure instruction, or statutory biometric deadline. You are responsible for choosing a duration that satisfies the laws that apply to your users; choose a shorter one whenever an applicable rule requires it.

Privacy erasure

Send deletion_instruction: "privacy_erasure" when you are acting on a data-subject request. Didit purges every retained biometric template anchored to the session’s User, then deletes the session and its embedding. The application retention policy cannot override a privacy-erasure instruction, and retain_face_embeddings: true is rejected with 400. Deleting the User with Batch Delete Users also purges its retained templates.

What is not affected

Deleting a session does not clean these up for you. If you are handling a right-to-erasure request, account for them separately.
  • Blocklist entries created from the session (face or document) stay in place. Remove them from the blocklist. A face blocklist entry keeps its own biometric entry, independent of any retained template.
  • Share tokens already issued for the session are not revoked, but there is nothing left for them to import: an import with one returns 400 with {"share_token": ["Original session does not exist."]}.
  • Webhooks already delivered for the session are not affected. Deliveries still queued, and their retries, are dropped. No webhook is emitted for the deletion itself.
  • Credits already consumed by the verification are not refunded.
  • Signed copies already emailed to a signer by an E-signature step are in the signer’s mailbox and are not affected.
  • The parent User or Business entity is not deleted. Use Delete Users or Delete Businesses for those. If the User’s profile portrait came from the deleted session, the portrait is removed.
  • A retained biometric template (only when you opted in) stays until it expires or you purge it. Purge it with the Biometric Templates API, by deleting the User, or by repeating the deletion of another session of the same User with deletion_instruction: "privacy_erasure".

Examples

Response on an application that has not opted in:

Errors

On 400 nothing is deleted. On 503 the session is still in place: repeat the same request until it returns 200. Some of its stored files or its face embedding may already be deleted, so do not rely on them after a 503.

Permission

Requires delete:sessions. The same permission covers both User Verification (KYC) and Business Verification (KYB) sessions, and the retention override.

Batch delete

For bulk operations on KYC sessions, use POST /v3/sessions/delete/. It accepts the same retention and instruction fields. Up to 20 matching sessions are deleted in the request with a per-session outcome; more run as a deletion job. See Batch Delete Sessions.

Migration from 204 responses

Until this release the endpoint returned 204 No Content. It now returns 200 OK with the JSON body documented above so that every deletion reports its face_retention_outcome. Update clients that assert on 204. The default behavior is unchanged: existing applications stay on delete_with_session, and no migration enables retention on your behalf. Enable it explicitly in the Console or through PATCH /v3/webhook/.

Authorizations

x-api-key
string
header
required

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is wrong, revoked or expired; 403 means no key was sent, the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

Headers

Idempotency-Key
string

Optional retry-safety key you choose for one operation, up to 255 characters (a UUID works). A request repeated with the same key, endpoint, query and body is answered with the first response, same status and same body, and runs and bills nothing a second time. The same key with another endpoint, query or body returns 409 idempotency_key_reused, and while the first request is still running, 409 idempotency_key_in_progress with Retry-After. A failed request (any 4xx or 5xx) is not stored, so you can send it again with the same key. Keys belong to your application, whether you call with an API key or an access token. See Retries and idempotency.

Required string length: 1 - 255

Path Parameters

sessionId
string<uuid>
required

UUID (session_id) of the User Verification (KYC) or Business Verification (KYB) session to delete, as returned when the session was created. Must be a canonical hyphenated UUID — a non-UUID value does not match the route and returns 404.

Example:

"11111111-2222-3333-4444-555555555555"

Body

application/json

Optional. Omit the body entirely to follow the application's retention policy with an operational deletion.

retain_face_embeddings
boolean | null

Override the application's face_retention_policy for this deletion. true keeps one image-free face biometric template anchored to the session's User after the session is deleted; false deletes the face embedding with the session; omit or null to follow the application policy. Ignored for KYB sessions and for sessions without a face embedding.

Example:

true

face_retention_days
integer

Finite retention duration, in days, for a retained template. Required when a template is retained unless the application already sets face_retention_days. The template's expires_at is the earliest of this duration, the application's general data-retention window, and face_retention_deadline.

Required range: 1 <= x <= 3650
Example:

365

face_retention_deadline
string<date-time>

Optional hard expiry for a retained template. Must be in the future.

Example:

"2027-08-28T00:00:00Z"

deletion_instruction
enum<string>
default:operational_session_delete

The class of instruction you are giving. operational_session_delete deletes the session and retains a template only when the policy or retain_face_embeddings says so. privacy_erasure purges every retained biometric template anchored to the session's User before deleting the session, cannot be overridden by the application policy, and cannot be combined with retain_face_embeddings: true (400).

Available options:
operational_session_delete,
privacy_erasure
Example:

"operational_session_delete"

instruction_id
string

Your durable reference for this deletion instruction (for example an erasure-ticket id). Recorded on the audit trail and on any retained template. Generated by Didit when omitted.

Maximum string length: 255
Example:

"dsar-2026-0142"

Response

Session deleted. The body reports what happened to the session's face biometric data and, for a KYB session, how many verifications it created were deleted with it.

session_id
string<uuid>

The deleted session.

session_number
integer | null

The deleted session's number.

face_retention_outcome
enum<string>

What happened to the session's face biometric data. deleted: the face embedding was deleted with the session (default). retained_with_user: the session is deleted and one image-free biometric template stays anchored to the User; see biometric_template_uuid. none: the session had no face embedding (for example a KYB session, or a KYC session without a liveness selfie). ineligible_no_vendor_user: retention was requested but the session has no linked User, so the embedding was deleted with the session. A biometric-store failure is never reported through this field on this endpoint: it returns 503 and the session is not deleted.

Available options:
retained_with_user,
deleted,
none,
ineligible_no_vendor_user
biometric_template_uuid
string<uuid> | null

Id of the retained biometric template when face_retention_outcome is retained_with_user; null otherwise. Manage it through /v3/biometric-templates/{template_uuid}/.

biometric_template_expires_at
string<date-time> | null

When the retained biometric template is deleted, when face_retention_outcome is retained_with_user; null when no template is retained.

deleted_child_verifications
integer

For a Business Verification (KYB) session: how many verifications it created (its key people's KYC sessions and its corporate owners' KYB sessions, recursively) were deleted with it. Always 0 for a KYC session.

Last modified on November 1, 2026