Didit Session & Workflow APIs

Overview

Sessions are the core unit of Didit verification. Every verification starts by creating a session linked to a workflow (configured in Console). The workflow defines what checks run (ID, liveness, AML, etc.) and the decision logic.

Base URL: https://verification.didit.me/v3

Session lifecycle:

Create Session → User verifies at URL → Receive webhook/poll decision → Optionally update status

Rate limits: 300 req/min per method. Session creation: 600 req/min. Decision polling: 100 req/min. On 429: check Retry-After header, use exponential backoff.

API Reference: https://docs.didit.me/reference/create-session-verification-sessions

Authentication

All requests require x-api-key header. Get your key from Didit Business Console → API & Webhooks.

Session Statuses

| Status | Description | Terminal |

|---|---|---|

| Not Started | Created, user hasn't begun | No |

| In Progress | User is completing verification | No |

| In Review | Needs manual review | No |

| Approved | Verification successful | Yes |

| Declined | Verification failed | Yes |

| Abandoned | User left without completing | Yes |

| Expired | Session expired (default: 7 days) | Yes |

| Resubmitted | Steps sent back for resubmission | No |

Workflow Types

Workflows are created in the Business Console (UI only, not via API). Each has a unique workflow_id.

| Template | Starts With | Use Case |

|---|---|---|

| KYC | ID Verification (OCR) | Full identity onboarding |

| Adaptive Age Verification | Selfie age estimation | Age-gated services (auto-fallback to ID if borderline) |

| Biometric Authentication | Liveness detection | Re-verify returning users (pass portrait_image) |

| Address Verification | Proof of Address | Residential address validation |

| Questionnaire | Custom questionnaire | Structured attestations and documents |

Two build modes:

Simple Mode: Toggle features on/off from a template
Advanced Mode: Visual node-based graph builder with conditional branches, parallel paths, action automation

Available features in workflows: ID Verification, Liveness, Face Match, NFC, AML Screening, Phone Verification, Email Verification, Proof of Address, Database Validation, IP Analysis, Age Estimation, Questionnaire.

1. Create Session

POST /v3/session/

| Header | Value | Required |

|---|---|---|

| x-api-key | Your API key | Yes |

| Content-Type | application/json | Yes |

Body (JSON)

|---|---|---|---|

| callback | url | No | Redirect URL. Didit appends verificationSessionId + status as query params |

| metadata | JSON string | No | Custom data stored with session. e.g. {"account_id": "ABC123"} |

Example

import requests

response = requests.post(
    "https://verification.didit.me/v3/session/",
    headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={
        "workflow_id": "d8d2fa2d-c69c-471c-b7bc-bc71512b43ef",
        "vendor_data": "user-123",
        "callback": "https://yourapp.com/callback",
        "language": "en",
    },
)
session = response.json()
# session["url"] → send user here to verify
# session["session_token"] → use for SDK initialization

const response = await fetch("https://verification.didit.me/v3/session/", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    workflow_id: "d8d2fa2d-c69c-471c-b7bc-bc71512b43ef",
    vendor_data: "user-123",
    callback: "https://yourapp.com/callback",
  }),
});
const session = await response.json();
// session.url → redirect user here

Response (201 Created)

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 1234,
  "session_token": "abcdef123456",
  "url": "https://verify.didit.me/session/abcdef123456",
  "vendor_data": "user-123",
  "status": "Not Started",
  "workflow_id": "d8d2fa2d-c69c-471c-b7bc-bc71512b43ef",
  "callback": "https://yourapp.com/callback"
}

| Error | Meaning | Action |

|---|---|---|

| 400 | Invalid workflow_id or insufficient credits | Verify workflow ID exists, check credits |

| 403 | No permission | Check API key permissions |

2. Retrieve Session (Get Decision)

GET /v3/session/{sessionId}/decision/

Returns all verification results for a completed session. Image/media URLs expire after 60 minutes.

Response (200 OK)

{
  "session_id": "...",
  "status": "Approved",
  "features": ["ID_VERIFICATION", "LIVENESS", "FACE_MATCH", "AML"],
  "vendor_data": "user-123",
  "id_verifications": [{"status": "Approved", "document_type": "...", "first_name": "..."}],
  "liveness_checks": [{"status": "Approved", "method": "ACTIVE_3D", "score": 89.92}],
  "face_matches": [{"status": "Approved", "score": 95.5}],
  "phone_verifications": [{"status": "Approved", "full_number": "+14155552671"}],
  "email_verifications": [{"status": "Approved", "email": "user@example.com"}],
  "aml_screenings": [{"status": "Approved", "total_hits": 0}],
  "poa_verifications": [...],
  "nfc_verifications": [...],
  "ip_analyses": [...],
  "database_validations": [...],
  "reviews": [...]
}

3. List Sessions

GET /v3/sessions/

| Query Param | Type | Description |

|---|---|---|

| vendor_data | string | Filter by your identifier |

| status | string | Filter by status |

| page | integer | Page number |

| page_size | integer | Results per page |

Response (200 OK)

{
  "count": 42,
  "next": "https://verification.didit.me/v3/sessions/?page=2",
  "previous": null,
  "results": [
    {"session_id": "...", "session_number": 34, "status": "Approved", "vendor_data": "user-123", "created_at": "..."}
  ]
}

response = requests.get(
    "https://verification.didit.me/v3/sessions/",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={"vendor_data": "user-123", "status": "Approved"},
)

4. Delete Session

DELETE /v3/session/{sessionId}/delete/

Permanently deletes a session and all associated data. Returns 204 No Content on success, 404 if not found.

response = requests.delete(
    f"https://verification.didit.me/v3/session/{session_id}/delete/",
    headers={"x-api-key": "YOUR_API_KEY"},
)
# response.status_code == 204 → success

5. Update Session Status

PATCH /v3/session/{sessionId}/update-status/

|---|---|---|---|

| nodes_to_resubmit | array | No | For Resubmitted: [{"node_id": "feature_ocr", "feature": "OCR"}] |

Resubmit: Session must be Declined, In Review, or Abandoned. Approved steps are preserved.

# Approve
requests.patch(f"https://verification.didit.me/v3/session/{session_id}/update-status/",
    headers=headers, json={"new_status": "Approved", "comment": "Manual review passed"})

# Resubmit specific steps with notification
requests.patch(f"https://verification.didit.me/v3/session/{session_id}/update-status/",
    headers=headers, json={
        "new_status": "Resubmitted",
        "nodes_to_resubmit": [{"node_id": "feature_ocr", "feature": "OCR"}],
        "send_email": True, "email_address": "user@example.com"
    })

6. Generate PDF Report

GET /v3/session/{sessionId}/generate-pdf

Generates a PDF verification report. Rate limited to 100 req/min (CPU-bound).

response = requests.get(
    f"https://verification.didit.me/v3/session/{session_id}/generate-pdf",
    headers={"x-api-key": "YOUR_API_KEY"},
)
# Returns PDF content or URL

7. Share Session

Generate a share_token for B2B KYC sharing. Only works for finished sessions (Approved, Declined, In Review).

POST /v3/session/{sessionId}/share/

response = requests.post(
    f"https://verification.didit.me/v3/session/{session_id}/share/",
    headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
)
share_token = response.json()["share_token"]
# Transmit share_token to partner via your backend

8. Import Shared Session

Used by the receiving partner to import a shared verification session.

POST /v3/session/import-shared/

|---|---|---|---|

response = requests.post(
    "https://verification.didit.me/v3/session/import-shared/",
    headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={
        "share_token": "eyJhbGciOiJIUzI1NiIs...",
        "trust_review": True,
        "workflow_id": "your-workflow-uuid",
        "vendor_data": "user-789",
    },
)

A session can only be imported once per partner application. Requires legal data sharing agreement + user consent.

9. Blocklist — Add

Block faces, documents, phones, emails from a session. Matching items auto-decline future sessions.

POST /v3/blocklist/add/

|---|---|---|---|---|

requests.post("https://verification.didit.me/v3/blocklist/add/",
    headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={"session_id": "...", "blocklist_face": True, "blocklist_document": True})

Auto-decline warnings when matched:

| Entity | Warning Tag |

|---|---|

| Face | FACE_IN_BLOCKLIST |

| Document | ID_DOCUMENT_IN_BLOCKLIST |

| Phone | PHONE_NUMBER_IN_BLOCKLIST |

| Email | EMAIL_IN_BLOCKLIST |

10. Blocklist — Remove

POST /v3/blocklist/remove/

|---|---|---|---|---|

requests.post("https://verification.didit.me/v3/blocklist/remove/",
    headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={"session_id": "...", "unblock_face": True})

11. Blocklist — List

GET /v3/blocklist/

| Query Param | Type | Description |

|---|---|---|

| item_type | string | Filter: "face", "document", "phone", "email". Omit for all |

Error Responses (All Endpoints)

| Code | Meaning | Action |

|---|---|---|

| 400 | Invalid request body or parameters | Check required fields and formats |

| 401 | Invalid or missing API key | Verify x-api-key header |

| 403 | Insufficient credits or no permission | Check credits in Business Console |

| 404 | Session not found | Verify session_id |

| 429 | Rate limited | Check Retry-After header, exponential backoff |

Common Workflows

Basic KYC Flow

1. POST /v3/session/ → create session with KYC workflow_id, get URL
2. Redirect user to session URL
3. Listen for webhook OR poll GET /v3/session/{id}/decision/
4. "Approved"  → user verified
   "Declined"  → check decision, optionally resubmit
   "In Review" → manual review or auto-decide via API

Programmatic Review + Blocklist

1. Receive webhook: status "In Review"
2. GET /v3/session/{id}/decision/ → inspect all results
3. Apply business logic
4. If fraud: PATCH → Declined + POST /v3/blocklist/add/ (block all entities)
   If legit: PATCH → Approved

B2B KYC Sharing

Service X:
1. POST /v3/session/{id}/share/ → get share_token
2. Transmit token to Service Y via backend

Service Y:
3. POST /v3/session/import-shared/ → import with trust_review=true
4. Session imported instantly with original status

Biometric Re-Authentication

1. Retrieve portrait_image from user's initial approved session
2. POST /v3/session/ → biometric auth workflow + portrait_image
3. User takes selfie → system matches against portrait
4. "Approved" → identity re-confirmed

Didit Sessionsv2.0.0

Install & Quick Start

Didit Session & Workflow APIs

Overview

Authentication

Session Statuses

Workflow Types

1. Create Session

Body (JSON)

Example

Response (201 Created)

2. Retrieve Session (Get Decision)

Response (200 OK)

3. List Sessions

Response (200 OK)

4. Delete Session

5. Update Session Status

6. Generate PDF Report

7. Share Session

8. Import Shared Session

9. Blocklist — Add

10. Blocklist — Remove

11. Blocklist — List

Error Responses (All Endpoints)

Common Workflows

Basic KYC Flow

Programmatic Review + Blocklist

B2B KYC Sharing

Biometric Re-Authentication

More security-identity Skills