Skip to main content
POST
curl

Behavior

Each matched session is deleted exactly as by Delete Session: the session, every verification attempt it holds, its decision and extracted data, its feature records, and all of its stored files are deleted, it disappears from every read endpoint, and previously issued media URLs stop resolving. Webhook deliveries still queued for a deleted session, and their retries, are dropped; webhooks already delivered are not affected. Deletion is permanent and irreversible. The number of matching sessions decides how the request is answered, whether you select them with session_numbers or with delete_all: A result confirms the session was deleted except when its face_retention_outcome is failed_retryable: that session was not deleted and is still in place, so treat that result as a failure to retry, never as deletion confirmation. Numbers that do not match a live KYC session in your application are skipped and do not appear in results.

Retention and instruction fields

The endpoint accepts the same optional fields as the single-session endpoint and applies them to every matched session: See Delete Session for what a retained template does and does not contain, how expires_at is computed, and what a privacy-erasure instruction does.

Per-session outcomes

For up to 20 matching sessions, 200 OK returns one result per session:
Each result carries the same fields as the Delete Session response. biometric_template_expires_at is when a retained template is deleted, and deleted_child_verifications is always 0 here because this endpoint deletes KYC sessions only. Sessions are deleted in groups. When a group cannot be deleted, every session in it is reported as failed_retryable; the other groups are unaffected and stay deleted.

Large selections run as a job

When more than 20 sessions match, the response is 202 Accepted with a deletion job instead of results:
Poll Get Session Deletion Job every few seconds until status is COMPLETED or FAILED.
  • The job reports how many sessions ended in each outcome, never which sessions it deleted.
  • A delete_all job deletes only the sessions created before your request. Sessions started while it runs are not deleted.
  • The retention and instruction fields of your request apply to every session the job deletes.
  • If a group cannot be deleted yet, the job retries it by itself.
  • A FAILED job explains why in error. The sessions it had not reached are still in place: repeat the request to delete them.

Examples

Migration from 204 responses

Until this release the endpoint returned 204 No Content. It now returns 200 OK with results[], or 202 Accepted with a deletion job for more than 20 matching sessions. Update clients that assert on 204. The default deletion behavior is unchanged: existing applications stay on delete_with_session until you explicitly change the policy.

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 missing, wrong, revoked or expired; 403 means 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.

Body

application/json
session_numbers
string[]

Numeric session_number values of the KYC sessions to delete, as digit-only strings (JSON numbers are also accepted and coerced). Required unless delete_all is true; an empty list returns 400. Any non-digit entry rejects the whole request with 400 (unless delete_all is true, in which case validation is skipped and the entries are ignored). Numbers that do not match a live session in your application are silently skipped.

Minimum array length: 1
Pattern: ^[0-9]+$
Example:
delete_all
boolean
default:false

When true, every remaining KYC session in the calling application is deleted and session_numbers is ignored. More than 20 matching sessions run as a deletion job (202) that covers only the sessions created before the request. Defaults to false. Irreversible; there is no confirmation step.

Example:

false

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

Up to 20 sessions matched and were processed in the request. One result per matched session; numbers that matched nothing (unknown or already deleted) are skipped and do not appear. A result confirms deletion except when face_retention_outcome is failed_retryable: that session was NOT deleted and should be retried.

results
object[]