curl -X DELETE \
https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \
-H 'x-api-key: YOUR_API_KEY'{
"session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
"session_number": 1024,
"face_retention_outcome": "deleted",
"biometric_template_uuid": null,
"biometric_template_expires_at": null,
"deleted_child_verifications": 0
}Delete Session API: GDPR Right-to-Be-Forgotten
Delete a KYC or KYB session and all of its data. By default the face embedding goes with it; opted-in applications can keep an image-free biometric template.
curl -X DELETE \
https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \
-H 'x-api-key: YOUR_API_KEY'{
"session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
"session_number": 1024,
"face_retention_outcome": "deleted",
"biometric_template_uuid": null,
"biometric_template_expires_at": null,
"deleted_child_verifications": 0
}KYC and KYB support
Works for both User Verification (KYC) and Business Verification (KYB) sessions. Thesession_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 expects204.
Data in a finalized regulatory report
If the session is part of a case with a finalized regulatory report, the request returns409 and nothing is deleted. The response uses code: in_filed_report and names each report:
{
"detail": "This session is part of a finalized regulatory report, so it cannot be deleted.",
"code": "in_filed_report",
"reports": [
{
"uuid": "5ec00000-0000-4000-8000-000000000007",
"report_number": "SAR-0001",
"report_type": "SAR",
"case_uuid": "c1a5e000-0000-4000-8000-000000000001"
}
]
}
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.
| Retained | Never retained |
|---|---|
| The numeric face template used for matching | The face image, liveness video, document images, portrait crops, and any other media |
A new random template id and an opaque provenance_reference | The deleted session’s id, number, decision, extracted identity fields, or feature payloads |
The owning User (vendor_user_uuid, current vendor_data) | Blocklist state, prior matches, fraud labels, or cross-organization identity claims |
Retention metadata: retained_at, expires_at, policy, override, instruction class, instruction_id, and the acting principal id | Actor email addresses |
- Application policy in Business Console → App Settings → Data retention or through
PATCH /v3/webhook/(face_retention_policy,face_retention_days). See Data retention. - Per-call override with
retain_face_embeddingson this endpoint and on Batch Delete Sessions. - Instruction class with
deletion_instruction. Aprivacy_erasureinstruction 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.| Field | Type | Description |
|---|---|---|
retain_face_embeddings | boolean or null | Override the application policy for this deletion. true retains a template, false deletes the embedding with the session, null or omitted follows the policy. |
face_retention_days | integer (1-3650) | Finite retention duration for the template. Required when a template is retained unless the application already sets face_retention_days. |
face_retention_deadline | datetime (ISO 8601) | Optional hard expiry. Must be in the future. |
deletion_instruction | operational_session_delete (default) or privacy_erasure | The class of instruction you are giving. privacy_erasure purges every retained template for the session’s User before deleting the session and cannot be combined with retain_face_embeddings: true. |
instruction_id | string (max 255) | Your durable reference for this instruction, for example your erasure-ticket id. Recorded on the audit trail and on any retained template. If you omit it Didit generates one, readable on the template detail. |
Response
{
"session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
"session_number": 1024,
"face_retention_outcome": "retained_with_user",
"biometric_template_uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b",
"biometric_template_expires_at": "2027-10-09T10:15:00Z",
"deleted_child_verifications": 0
}
| Field | Description |
|---|---|
session_id | The deleted session. |
session_number | The deleted session’s number. |
face_retention_outcome | What happened to the session’s face biometric data. See the table below. |
biometric_template_uuid | Id of the retained biometric template when face_retention_outcome is retained_with_user; null otherwise. |
biometric_template_expires_at | When the retained biometric template is deleted; null when no template is retained. |
deleted_child_verifications | For a 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. |
face_retention_outcome | Meaning |
|---|---|
deleted | The session and its face embedding are deleted. Default behavior. |
retained_with_user | The session is deleted. One image-free biometric template stays anchored to the User; its id is biometric_template_uuid. Manage it with the Biometric Templates API. |
none | The session had no face embedding to delete or retain (for example a KYB session, or a KYC session without a liveness selfie). |
ineligible_no_vendor_user | Retention was requested, but the session is not linked to a User (it was created without vendor_data), so nothing can anchor a template. The session and its embedding are deleted. The ineligible outcome is recorded on the audit trail. |
instruction_id in your own erasure log so you can correlate the audit trail later.
Retention duration and expiry
Every retained template has a finiteexpires_at. Didit sets it to the earliest of:
face_retention_daysfrom the request, or the application’sface_retention_dayswhen the request omits it;- the application’s general data-retention window, when one is configured;
face_retention_deadlinefrom the request, when provided.
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
Senddeletion_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
400with{"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
- Default (application policy)
- Retain a biometric template
- Force deletion on an opted-in app
- Privacy erasure
- Session without a User
- Business Verification (KYB) session
curl -X DELETE https://verification.didit.me/v3/session/4c5c7f3a-.../delete/ \
-H "x-api-key: YOUR_API_KEY"
{
"session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
"session_number": 1024,
"face_retention_outcome": "deleted",
"biometric_template_uuid": null,
"biometric_template_expires_at": null,
"deleted_child_verifications": 0
}
curl -X DELETE https://verification.didit.me/v3/session/4c5c7f3a-.../delete/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"retain_face_embeddings": true, "face_retention_days": 365, "instruction_id": "cleanup-2026-08-0142"}'
{
"session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
"session_number": 1024,
"face_retention_outcome": "retained_with_user",
"biometric_template_uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b",
"biometric_template_expires_at": "2027-10-09T10:15:00Z",
"deleted_child_verifications": 0
}
curl -X DELETE https://verification.didit.me/v3/session/4c5c7f3a-.../delete/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"retain_face_embeddings": false}'
{
"session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
"session_number": 1024,
"face_retention_outcome": "deleted",
"biometric_template_uuid": null,
"biometric_template_expires_at": null,
"deleted_child_verifications": 0
}
curl -X DELETE https://verification.didit.me/v3/session/4c5c7f3a-.../delete/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"deletion_instruction": "privacy_erasure", "instruction_id": "dsar-2026-0142"}'
{
"session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
"session_number": 1024,
"face_retention_outcome": "deleted",
"biometric_template_uuid": null,
"biometric_template_expires_at": null,
"deleted_child_verifications": 0
}
vendor_data has no User to anchor a template to:curl -X DELETE https://verification.didit.me/v3/session/7a1e9c2d-.../delete/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"retain_face_embeddings": true, "face_retention_days": 365}'
{
"session_id": "7a1e9c2d-5f4b-4c3a-8e2d-1b0a9f8e7d6c",
"session_number": 1031,
"face_retention_outcome": "ineligible_no_vendor_user",
"biometric_template_uuid": null,
"biometric_template_expires_at": null,
"deleted_child_verifications": 0
}
curl -X DELETE https://verification.didit.me/v3/session/bs-01HJX1.../delete/ \
-H "x-api-key: YOUR_API_KEY"
{
"session_id": "0f3c9b7e-2d1a-4e5f-8c6b-7a9d8e1f2c3b",
"session_number": 88,
"face_retention_outcome": "none",
"biometric_template_uuid": null,
"biometric_template_expires_at": null,
"deleted_child_verifications": 3
}
Errors
| Status | When | Body |
|---|---|---|
400 | privacy_erasure combined with retain_face_embeddings: true | {"retain_face_embeddings": ["Privacy erasure cannot retain biometric templates."]} |
400 | Retention requested without a finite duration on the request or the application | {"detail": "A finite biometric-template retention duration is required."} |
403 | The credential lacks delete:sessions or does not own the session | {"detail": "You do not have permission to perform this action."} |
404 | Unknown or already-deleted session | {"detail": "Not found."} |
503 | A storage service or a monitoring provider was unavailable while deleting the session. | {"detail": "The session could not be deleted because a storage service or a monitoring provider is unavailable. The session is still in place; repeat the request to finish deleting it."} |
503 | A biometric store was unavailable while retaining or purging a template. Retries converge on a single template. | {"detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable."} |
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
Requiresdelete: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, usePOST /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 returned204 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/.
Related
Authorizations
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
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.
1 - 255Path Parameters
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.
"11111111-2222-3333-4444-555555555555"
Body
Optional. Omit the body entirely to follow the application's retention policy with an operational deletion.
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.
true
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.
1 <= x <= 3650365
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).
operational_session_delete, privacy_erasure "operational_session_delete"
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.
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.
retained_with_user, deleted, none, ineligible_no_vendor_user