How do I install the Didit Sessions skill?

Run npx skillmds@latest add modbender/didit-sessions in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Didit Sessions skill do?

Integrate Didit Session & Workflow APIs — the central hub for managing verification sessions. Use when the user wants to create a verification session, set up a KYC workflow, create a session with a workflow_id, retrieve session results, get session decisions, list sessions, delete sessions, update session status, approve or decline sessions, request resubmission, generate PDF reports, share sessions between partners, import shared sessions, add or remove users from blocklist, manage blocked faces/documents/phones/emails, handle webhooks, or implement any end-to-end verification flow using Didit. Covers 11 API endpoints: create, retrieve, list, delete, update-status, generate-pdf, share, import-shared, blocklist-add, blocklist-remove, blocklist-list. It is listed under Docs & Writing on SkillMD.

Is Didit Sessions safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: CAUTION, Skill Scanner: PASS. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Didit Sessions?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Didit Sessions free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Didit Sessions?

modbender (@modbender) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Didit Sessions by modbender — Agent Skill

Name: Didit Sessions
Rating: 4.666666666666667 (3 reviews)
Author: modbender

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)

Parameter	Type	Required	Description
`workflow_id`	uuid	Yes	Workflow ID from Console → Workflows
`vendor_data`	string	No	Your identifier (UUID/email) for tracking
`callback`	url	No	Redirect URL. Didit appends `verificationSessionId` + `status` as query params
`callback_method`	string	No	`"initiator"` (default), `"completer"`, or `"both"` — which device handles redirect
`metadata`	JSON string	No	Custom data stored with session. e.g. `{"account_id": "ABC123"}`
`language`	string	No	ISO 639-1 code for UI language (auto-detected if omitted)
`contact_details.email`	string	No	Pre-fill email for email verification step
`contact_details.phone`	string	No	Pre-fill phone (E.164) for phone verification step
`contact_details.send_notification_emails`	boolean	No	Send status update emails (default: `false`)
`expected_details.first_name`	string	No	Expected first name (triggers mismatch warning if different)
`expected_details.last_name`	string	No	Expected last name
`expected_details.date_of_birth`	string	No	Expected DOB (`YYYY-MM-DD`)
`expected_details.gender`	string	No	`"M"`, `"F"`, or `null`
`expected_details.nationality`	string	No	ISO 3166-1 alpha-3 (e.g. `USA`)
`portrait_image`	base64	No	Reference portrait for Biometric Auth workflows (max 1MB)

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/

Parameter	Type	Required	Description
`new_status`	string	Yes	`"Approved"`, `"Declined"`, or `"Resubmitted"`
`comment`	string	No	Reason for status change
`send_email`	boolean	No	Send email notification (default: `false`)
`email_address`	string	No*	Required when `send_email` is `true`
`email_language`	string	No	Language for email (default: `"en"`)
`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/

Parameter	Type	Required	Description
`share_token`	string	Yes	Token from the sharing partner
`trust_review`	boolean	Yes	`true`: keep original status. `false`: set to "In Review"
`workflow_id`	string	Yes	Your workflow ID to associate
`vendor_data`	string	No	Your own user identifier

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/

Parameter	Type	Required	Default	Description
`session_id`	uuid	Yes	—	Session to blocklist items from
`blocklist_face`	boolean	No	`false`	Block biometric face template
`blocklist_document`	boolean	No	`false`	Block document fingerprint
`blocklist_phone`	boolean	No	`false`	Block phone number
`blocklist_email`	boolean	No	`false`	Block email address

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/

Parameter	Type	Required	Default	Description
`session_id`	uuid	Yes	—	Session to unblock items from
`unblock_face`	boolean	No	`false`	Unblock face
`unblock_document`	boolean	No	`false`	Unblock document
`unblock_phone`	boolean	No	`false`	Unblock phone
`unblock_email`	boolean	No	`false`	Unblock email

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 Sessions

File contents

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

Frequently asked questions

Didit Sessions

File contents

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

Related skills

Frequently asked questions

How do I install the Didit Sessions skill?

What does the Didit Sessions skill do?

Is Didit Sessions safe to use?

Which AI agents work with Didit Sessions?

Is Didit Sessions free to use?

Who published Didit Sessions?