Delete Session - Didit Documentation

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
}

DELETE

session

{sessionId}

delete

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
}

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, together with its decision, its extracted data, its associated feature records (ID verifications, registry checks, documents, AML, IP analysis, and so on) and all of its stored media.
The session disappears from list and decision responses immediately, and media URLs issued before the call stop resolving.
Deletion is 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 with a JSON body that reports what happened to the session’s face biometric data. See Migration if your client still expects 204.

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:

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

Retention is configured in three places, from broadest to most specific:

Application policy in Business Console → App Settings → Data or through PATCH /v3/webhook/ (face_retention_policy, face_retention_days). See Data retention.
Per-call override with retain_face_embeddings on this endpoint and on Batch Delete Sessions.
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.

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"
}

`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.

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:

face_retention_days from the request, or the application’s face_retention_days when the request omits it;
the application’s general data-retention window, when one is configured;
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.
Hosted-flow share tokens already issued for the session are not revoked.
Webhook deliveries already queued still arrive, and no webhook is emitted for the deletion itself.
Credits already consumed by the verification are not refunded.
The parent User or Business entity is not deleted. Use Delete Users or Delete Businesses for those.
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

curl -X DELETE https://verification.didit.me/v3/session/4c5c7f3a-.../delete/ \
  -H "x-api-key: YOUR_API_KEY"

Response on an application that has not opted in:

{
  "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
  "session_number": 1024,
  "face_retention_outcome": "deleted",
  "biometric_template_uuid": null
}

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"
}

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
}

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"}'

Every retained template for the session’s User is purged first, then the session is deleted:

{
  "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
  "session_number": 1024,
  "face_retention_outcome": "deleted",
  "biometric_template_uuid": null
}

A session created without 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
}

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
}

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 biometric store was unavailable while retaining or purging a template. The session is not deleted and the source embedding is untouched. Repeat the same request; retries converge on a single template.	`{"detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable."}`

On 400 and 503 nothing is deleted.

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, use POST /v3/sessions/delete/. It accepts the same retention and instruction fields and returns a per-session outcome. 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

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.

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). 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}/.

​KYC and KYB support

​Behavior

​Face biometric data: delete or retain

​Request body

​Response

​Retention duration and expiry

​Privacy erasure

​What is not affected

​Examples

​Errors

​Permission

​Batch delete

​Migration from 204 responses

​Related

Authorizations

Path Parameters

Body

Response

KYC and KYB support

Behavior

Face biometric data: delete or retain

Request body

Response

Retention duration and expiry

Privacy erasure

What is not affected

Examples

Errors

Permission

Batch delete

Migration from 204 responses

Related