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

# Delete Session

> Soft-delete a single verification session — User Verification (KYC) or Business Verification (KYB) — by its `session_id`. The id is resolved against KYC sessions first, then KYB sessions, so both kinds are deleted through this one URL.

**What happens on deletion:**
- The session is stamped with a deletion timestamp and immediately disappears from every read endpoint — `GET /v3/session/{sessionId}/decision/` returns `404` and `GET /v3/sessions/` stops listing it.
- For KYC sessions, related face, liveness, and face-match records are soft-deleted together with the session.
- A background job then moves every stored media file owned by the session to a quarantined storage prefix: document front/back photos (full, cropped, and privacy-blurred variants), document-capture videos, portrait crops, NFC chip portrait and signature images, face reference images, liveness videos, face-match source/target images, Proof of Address documents, and any extra uploaded files (KYC); uploaded company documents and extra files (KYB). Previously issued media URLs (`https://<media-host>/...`) stop resolving once the move completes — the move is asynchronous, so a URL issued just before deletion may keep working for a short window after the `204`.

**What is retained:** the underlying database records (decision, extracted data, audit events) are kept internally, marked with the deletion timestamp — they become unreachable through the API but are not erased at the moment of the call. Blocklist entries created from this session (face or document) are **not** removed — manage those with the blocklist endpoints. Credits already consumed are not refunded.

**Irreversible:** there is no restore/undelete endpoint.

**Side effects:** no webhook is emitted for deletions.

**Idempotency:** not idempotent at the HTTP level — the first call returns `204`; repeating it returns `404` because the session no longer resolves.

**Authentication:** send your application's API key in the `x-api-key` header; the session must belong to that application. Console user access tokens (`Authorization: Bearer ...`) may also call this endpoint when they carry the `delete:sessions` permission. Authentication and permission failures both return `403` — this API never returns `401`.

**Rate limit:** shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints; exceeding it returns `429`.

To bulk-delete KYC sessions by their numeric `session_number`, use `POST /v3/sessions/delete/` instead.

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 <div className="didit-agent-card">
      {}
      <div className="didit-agent-titlebar">
        <div className="didit-agent-dots" aria-hidden="true">
          <span className="didit-agent-dot didit-agent-dot-red"></span>
          <span className="didit-agent-dot didit-agent-dot-yellow"></span>
          <span className="didit-agent-dot didit-agent-dot-green"></span>
        </div>
        <span className="didit-agent-filename">{title}</span>
        <button type="button" className={`didit-agent-copy ${copied ? "didit-agent-copy-copied" : ""}`} onClick={handleCopy} title="Copy prompt to clipboard" aria-label={copied ? "Copied!" : "Copy prompt to clipboard"}>
          {copied ? <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <path d="M3 8.5l3.5 3.5L13 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
              </svg>
              <span>Copied</span>
            </> : <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <rect x="5" y="5" width="9" height="9" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
                <path d="M11 5V3.5A1.5 1.5 0 0 0 9.5 2h-6A1.5 1.5 0 0 0 2 3.5v6A1.5 1.5 0 0 0 3.5 11H5" stroke="currentColor" strokeWidth="1.5" />
              </svg>
              <span>Copy</span>
            </>}
        </button>
      </div>

      {}
      <pre className="didit-agent-body"><code>{prompt.trim()}</code></pre>

      {}
      <div className="didit-agent-footer">
        <span className="didit-agent-footer-label">Paste into</span>
        <div className="didit-agent-chips">
          {agents.map(name => <span key={name} className="didit-agent-chip">{name}</span>)}
        </div>
      </div>
    </div>;
};

<AgentPromptAccordion
  title="Delete Session Prompt"
  prompt={`Soft-delete a single Didit verification session.

Endpoint:
DELETE https://verification.didit.me/v3/session/{session_id}/delete/

Authentication:
Use the x-api-key header with your Didit API key. Privilege: delete:sessions.

Path parameter:
- session_id (UUID) — works for both User Verification (KYC) and Business Verification (KYB) sessions. Didit looks up the value in both tables.

curl example:
curl -X DELETE https://verification.didit.me/v3/session/<SESSION_ID>/delete/ \\
-H "x-api-key: <API_KEY>"

Response:
- 204 No Content on success — no body.

Behavior:
- Sets deleted_at on the session row (soft delete). The row remains in the database until your configured data-retention window (see /console/data-retention) expires, then is hard-deleted.
- Associated feature records (id_verifications, registry_checks, documents, AML, IP, etc.) and activity logs stop appearing in /v3/sessions and /v3/session/{id}/decision/ immediately.
- The link to the parent entity (User or Business) is preserved in history; the session itself no longer appears in list endpoints.
- Hosted-flow share tokens and already-queued webhook deliveries are NOT revoked.
- No webhook fires for the deletion itself.

Idempotency:
Idempotent in effect — the second call to the same session returns 404 because the soft-deleted row is filtered out. There is no undo via API.

Failure modes:
- 401 — invalid API key.
- 403 — { "detail": "You do not have permission to perform this action." } when the key lacks delete:sessions.
- 404 — { "detail": "Not found." } when the session does not exist (or was already deleted).

Bulk delete:
For many sessions at once, use POST /v3/sessions/delete/ with body { "session_numbers": [1, 2, 3] } or { "delete_all": true }.

When to call:
- Customer requests data erasure (GDPR Article 17).
- Cleaning up test sessions from a staging application.
- After exporting a decision PDF for long-term archival outside Didit.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`}
/>

## KYC and KYB support

Works for both **User Verification (KYC)** and **Business Verification (KYB)** sessions. The `session_id` is looked up in both tables; the same delete behavior applies to both.

## Behavior

* Session is deleted — `deleted_at` is set. The row remains in the database for your configured [data retention](/console/data-retention) window, then is hard-deleted.
* Associated feature records (ID verifications, registry checks, documents, etc.) are deleted alongside.
* Links to the parent entity (User or Business) are preserved in history but the session itself no longer appears in list responses.

## Examples

<Tabs>
  <Tab title="Delete a User Verification (KYC) session">
    ```bash theme={null}
    curl -X DELETE https://verification.didit.me/v3/session/4c5c7f3a-.../delete/ \
      -H "x-api-key: YOUR_API_KEY"
    ```

    Response: `204 No Content`.
  </Tab>

  <Tab title="Delete a Business Verification (KYB) session">
    ```bash theme={null}
    curl -X DELETE https://verification.didit.me/v3/session/bs-01HJX1.../delete/ \
      -H "x-api-key: YOUR_API_KEY"
    ```

    Response: `204 No Content`.
  </Tab>
</Tabs>

## Permission

Requires `delete:sessions`. The same permission covers both User Verification (KYC) and Business Verification (KYB) sessions.

## Batch delete

For bulk operations, use `POST /v3/sessions/delete/` — accepts a list of session IDs of either kind.

## Related

* [Data retention](/console/data-retention)
* [Sessions overview](/sessions-api/overview)


## OpenAPI

````yaml DELETE /v3/session/{sessionId}/delete/
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/session/{sessionId}/delete/:
    delete:
      tags:
        - Sessions
      summary: Soft-delete a verification session (KYC or KYB)
      description: >-
        Soft-delete a single verification session — User Verification (KYC) or
        Business Verification (KYB) — by its `session_id`. The id is resolved
        against KYC sessions first, then KYB sessions, so both kinds are deleted
        through this one URL.


        **What happens on deletion:**

        - The session is stamped with a deletion timestamp and immediately
        disappears from every read endpoint — `GET
        /v3/session/{sessionId}/decision/` returns `404` and `GET /v3/sessions/`
        stops listing it.

        - For KYC sessions, related face, liveness, and face-match records are
        soft-deleted together with the session.

        - A background job then moves every stored media file owned by the
        session to a quarantined storage prefix: document front/back photos
        (full, cropped, and privacy-blurred variants), document-capture videos,
        portrait crops, NFC chip portrait and signature images, face reference
        images, liveness videos, face-match source/target images, Proof of
        Address documents, and any extra uploaded files (KYC); uploaded company
        documents and extra files (KYB). Previously issued media URLs
        (`https://<media-host>/...`) stop resolving once the move completes —
        the move is asynchronous, so a URL issued just before deletion may keep
        working for a short window after the `204`.


        **What is retained:** the underlying database records (decision,
        extracted data, audit events) are kept internally, marked with the
        deletion timestamp — they become unreachable through the API but are not
        erased at the moment of the call. Blocklist entries created from this
        session (face or document) are **not** removed — manage those with the
        blocklist endpoints. Credits already consumed are not refunded.


        **Irreversible:** there is no restore/undelete endpoint.


        **Side effects:** no webhook is emitted for deletions.


        **Idempotency:** not idempotent at the HTTP level — the first call
        returns `204`; repeating it returns `404` because the session no longer
        resolves.


        **Authentication:** send your application's API key in the `x-api-key`
        header; the session must belong to that application. Console user access
        tokens (`Authorization: Bearer ...`) may also call this endpoint when
        they carry the `delete:sessions` permission. Authentication and
        permission failures both return `403` — this API never returns `401`.


        **Rate limit:** shared write budget of 300 requests/min per API key
        across all POST/PATCH/DELETE endpoints; exceeding it returns `429`.


        To bulk-delete KYC sessions by their numeric `session_number`, use `POST
        /v3/sessions/delete/` instead.
      operationId: delete_v3_session_by_id
      parameters:
        - in: path
          name: sessionId
          required: true
          description: >-
            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`.
          schema:
            type: string
            format: uuid
            example: 11111111-2222-3333-4444-555555555555
      responses:
        '204':
          description: >-
            Session soft-deleted. Empty body. The media quarantine continues
            asynchronously after the response.
        '403':
          description: >-
            Authentication or permission failure. Missing/invalid credentials
            also return `403` — this API never returns `401`. Exception: when
            the `sessionId` does not resolve to a live session, the pre-auth
            owner lookup returns `404` first, even with missing or invalid
            credentials.
          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: >-
                      Authentication credentials were not provided or are
                      invalid.
                Insufficient permission:
                  summary: >-
                    User token without delete:sessions, or credentials for an
                    application that does not own the session
                  value:
                    detail: You do not have permission to perform this action.
        '404':
          description: >-
            No live KYC or KYB session with this `session_id` exists — the id is
            unknown or the session was already soft-deleted (repeating a
            successful delete lands here).
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                Not Found:
                  summary: Unknown or already-deleted session
                  value:
                    detail: Not found.
        '429':
          description: >-
            Shared write rate limit exceeded (300 POST/PATCH/DELETE requests per
            minute per API key). Inspect `Retry-After` and the `X-RateLimit-*`
            response headers before retrying.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                Rate limited:
                  summary: Write budget exhausted
                  value:
                    detail: >-
                      Write request rate limit exceeded. You can make up to 300
                      requests per minute.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X DELETE \
              https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \
              -H 'x-api-key: YOUR_API_KEY'
        - lang: python
          label: Python
          source: >-
            import requests


            response = requests.delete(
                "https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/",
                headers={"x-api-key": "YOUR_API_KEY"},
            )

            response.raise_for_status()  # 204 on success; 404 if unknown or
            already deleted
        - lang: javascript
          label: JavaScript
          source: >-
            const response = await fetch(
              'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/',
              {
                method: 'DELETE',
                headers: { 'x-api-key': 'YOUR_API_KEY' },
              },
            );

            if (response.status !== 204) throw new Error(`HTTP
            ${response.status}`);
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````