> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Session Deletion Job
> Poll the status and outcome counts of a bulk session deletion that Batch Delete Sessions answered with 202 because more than 20 sessions matched.
export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
const [copied, setCopied] = React.useState(false);
const handleCopy = e => {
e.stopPropagation();
if (!prompt) return;
navigator.clipboard.writeText(prompt.trim()).then(() => {
setCopied(true);
setTimeout(() => setCopied(false), 2000);
});
};
const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
return
{}
{title}
{}
{prompt.trim()}
{}
Paste into
{agents.map(name => {name})}
;
};
Path param:
- job_id: the job_id returned with the 202.
curl:
curl 'https://verification.didit.me/v3/sessions/delete/JOB_ID/' \\
-H 'x-api-key: YOUR_API_KEY'
Response 200:
{
"job_id": "",
"status": "PROCESSING", // PENDING | PROCESSING | COMPLETED | FAILED
"total": 250, // sessions selected when the deletion was requested
"processed": 100, // sessions the job has finished with so far
"outcomes": {"deleted": 82, "none": 18, "retained_with_user": 0, "ineligible_no_vendor_user": 0, "failed_retryable": 0, "already_deleted": 0},
"deleted_child_verifications": 0, // always 0 for jobs from POST /v3/sessions/delete/ (KYC sessions only)
"error": null, // why the deletion stopped, when status is FAILED
"created_at": "",
"completed_at": null
}
outcomes counts:
- deleted: sessions deleted together with their face embedding.
- none: sessions deleted that had no face embedding.
- retained_with_user: sessions deleted while one image-free biometric template was retained for their User, as the request or the application policy asked.
- ineligible_no_vendor_user: retention was requested but the session had no linked User; the session and its embedding were deleted.
- failed_retryable: sessions reported as not deleted. The job retries a group it could not delete by itself instead of counting it here.
- already_deleted: selected sessions that were already deleted, for example by another request, when the job reached them.
Polling: request the job every few seconds while status is PENDING or PROCESSING; stop at COMPLETED or FAILED. The job never lists which sessions it deleted, only counts. A FAILED job explains why in error; the sessions it had not reached are still in place, so repeat the deletion request to delete them. Deletion is permanent and irreversible.
Failure modes:
- 403: missing or invalid x-api-key. { "detail": "You do not have permission to perform this action." }
- 404: no such job for this application (a job is only visible to the application that created it).
For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`}
/>
## Overview
Returns a bulk session deletion started by [Batch Delete Sessions](/management-api/sessions/batch-delete): its status, how many sessions it has processed, and how many ended in each outcome.
When more than 20 KYC sessions match a batch delete, selected by `session_numbers` or with `delete_all`, the request returns `202` with a `PENDING` job and the sessions are deleted in the background. Poll this endpoint every few seconds until `status` is `COMPLETED` or `FAILED`.
Each session the job deletes is deleted exactly as by [Delete Session](/sessions-api/delete-session): the session, every verification attempt it holds, and all of its stored files are deleted, and its media URLs stop resolving. Deletion is permanent and irreversible.
The job reports counts only. It never lists which sessions it deleted.
## Job status
| `status` | Meaning |
| - | - |
| `PENDING` | Accepted, not started yet. |
| `PROCESSING` | Deleting; `processed` and `outcomes` are updating. |
| `COMPLETED` | Every selected session is accounted for in `outcomes`. |
| `FAILED` | The job stopped early and `error` says why. The sessions it had not reached are still in place: repeat the deletion request to delete them. |
A `delete_all` job deletes only the sessions created before the request. Sessions started while it runs are not deleted.
## Outcome counts
| `outcomes` key | Meaning |
| - | - |
| `deleted` | Sessions deleted together with their face embedding. |
| `none` | Sessions deleted that had no face embedding. |
| `retained_with_user` | Sessions deleted while one image-free biometric template was retained for their User, as the request or the application policy asked. See [Delete Session](/sessions-api/delete-session#face-biometric-data-delete-or-retain). |
| `ineligible_no_vendor_user` | Retention was requested but the session had no linked User. The session and its face embedding were deleted. |
| `failed_retryable` | Sessions reported as not deleted. The job retries a group it could not delete by itself instead of counting it here. |
| `already_deleted` | Selected sessions that were already deleted, for example by another request, when the job reached them. |
`deleted_child_verifications` counts the verifications that deleted business verifications created and that were deleted with them. It is always `0` for a job started by [Batch Delete Sessions](/management-api/sessions/batch-delete), which deletes KYC sessions only.
## Permissions
Any active API key of the application can call this endpoint. A job is only visible to the application that created it; any other `job_id` returns `404`.
## Related
* [Batch Delete Sessions](/management-api/sessions/batch-delete)
* [Delete Session](/sessions-api/delete-session)
* [Data retention](/console/data-retention)
## OpenAPI
````yaml GET /v3/sessions/delete/{job_id}/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: Identity verification API. Authenticate with x-api-key header.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/sessions/delete/{job_id}/:
get:
tags:
- Sessions
summary: Get a bulk session deletion job
description: >-
Progress of a bulk session deletion that `POST /v3/sessions/delete/`
answered with `202` (more than 20 matching sessions, selected by
`session_numbers` or with `delete_all`). Poll every few seconds while
`status` is `PENDING` or `PROCESSING`; stop when it is `COMPLETED` or
`FAILED`.
The job reports how many sessions ended in each outcome and how many it
has processed, never which sessions it deleted. A `FAILED` job carries
the reason in `error`; the sessions it had not reached are still in
place, so repeat the deletion request to delete them.
**Authentication:** API key in the `x-api-key` header. A job is only
visible to the application that created it; any other `job_id` returns
`404`. Missing or invalid credentials return `403`; this API never
returns `401`.
operationId: get_session_deletion_job
parameters:
- name: job_id
in: path
required: true
schema:
type: string
format: uuid
description: >-
The `job_id` returned with the `202` from `POST
/v3/sessions/delete/`.
responses:
'200':
description: The job.
content:
application/json:
schema:
type: object
description: >-
A bulk session deletion running in the background: progress
and counts per outcome, never which sessions it deleted.
properties:
job_id:
type: string
format: uuid
description: Poll `GET /v3/sessions/delete/{job_id}/` with this id.
status:
type: string
enum:
- PENDING
- PROCESSING
- COMPLETED
- FAILED
description: >-
`PENDING`: accepted, not started yet. `PROCESSING`:
deleting; `processed` and `outcomes` are updating.
`COMPLETED`: every selected session is accounted for.
`FAILED`: the job stopped early; see `error`.
total:
type: integer
description: Sessions selected when the deletion was requested.
processed:
type: integer
description: Sessions the job has finished with so far.
outcomes:
type: object
description: >-
How many sessions ended in each outcome. Every key is
always present.
properties:
deleted:
type: integer
description: Sessions deleted together with their face embedding.
none:
type: integer
description: Sessions deleted that had no face embedding.
retained_with_user:
type: integer
description: >-
Sessions deleted while one image-free biometric
template was retained for their User, as the request
or the application policy asked.
ineligible_no_vendor_user:
type: integer
description: >-
Sessions deleted, with their face embedding, because
retention was requested but they had no linked User.
failed_retryable:
type: integer
description: >-
Sessions reported as not deleted. A job retries a
group it could not delete by itself instead of
counting it here.
already_deleted:
type: integer
description: >-
Selected sessions that were already deleted, for
example by another request, when the job reached them.
deleted_child_verifications:
type: integer
description: >-
Verifications that the deleted business verifications
created, deleted with them. Always `0` for a job started
by `POST /v3/sessions/delete/`, which deletes KYC sessions
only.
error:
type: string
nullable: true
description: >-
`null` unless `status` is `FAILED`; then why the deletion
stopped. The sessions the job had not reached are still in
place: repeat the request to delete them.
created_at:
type: string
format: date-time
description: When the deletion was requested.
completed_at:
type: string
format: date-time
nullable: true
description: When the job finished; `null` while it runs.
examples:
Processing:
value:
job_id: 5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b
status: PROCESSING
total: 250
processed: 100
outcomes:
deleted: 82
none: 18
retained_with_user: 0
ineligible_no_vendor_user: 0
failed_retryable: 0
already_deleted: 0
deleted_child_verifications: 0
error: null
created_at: '2026-10-09T10:15:00Z'
completed_at: null
Completed:
value:
job_id: 5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b
status: COMPLETED
total: 250
processed: 250
outcomes:
deleted: 204
none: 44
retained_with_user: 0
ineligible_no_vendor_user: 0
failed_retryable: 0
already_deleted: 2
deleted_child_verifications: 0
error: null
created_at: '2026-10-09T10:15:00Z'
completed_at: '2026-10-09T10:16:40Z'
Failed:
value:
job_id: 5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b
status: FAILED
total: 250
processed: 100
outcomes:
deleted: 82
none: 18
retained_with_user: 0
ineligible_no_vendor_user: 0
failed_retryable: 0
already_deleted: 0
deleted_child_verifications: 0
error: >-
The deletion stopped before it finished. The sessions it
had not reached are still in place; repeat the request to
delete them.
created_at: '2026-10-09T10:15:00Z'
completed_at: '2026-10-09T10:15:52Z'
'403':
description: >-
Missing or invalid API key. This API returns `403` for
authentication failures, never `401`.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
examples:
Missing or invalid API key:
summary: No x-api-key header, or the key is invalid
value:
detail: You do not have permission to perform this action.
'404':
description: >-
No deletion job with this `job_id` exists for the calling
application. Jobs are only visible to the application that created
them.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: |-
curl 'https://verification.didit.me/v3/sessions/delete/JOB_ID/' \
-H 'x-api-key: YOUR_API_KEY'
- lang: python
label: Python
source: |-
import time
import requests
url = 'https://verification.didit.me/v3/sessions/delete/JOB_ID/'
while True:
job = requests.get(url, headers={'x-api-key': 'YOUR_API_KEY'}).json()
if job['status'] in ('COMPLETED', 'FAILED'):
break
time.sleep(3)
print(job['status'], job['outcomes'], job['error'])
- lang: javascript
label: JavaScript
source: >-
const url =
'https://verification.didit.me/v3/sessions/delete/JOB_ID/';
let job;
do {
await new Promise((r) => setTimeout(r, 3000));
job = await (await fetch(url, { headers: { 'x-api-key': 'YOUR_API_KEY' } })).json();
} while (job.status === 'PENDING' || job.status === 'PROCESSING');
console.log(job.status, job.outcomes, job.error);
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
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.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.