AGENT SKILL

didit-sessions

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.

License 许可
MIT
最近更新
2026-06-07
Stars
★ 0
Forks
1

01 前言 Front Matter

name
didit-sessions
version
2.0.0
metadata
{ "openclaw": { "emoji": "🔄", "homepage": "https://docs.didit.me", "requires": { "env": [ "DIDIT_API_KEY", "DIDIT_WORKFLOW_ID" ] }, "primaryEnv": "DIDIT_API_KEY" } }
description
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.

03 SKILL.md 正文

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

04 同仓库更多 Skills

javimosch
javimosch/open-claw-skills

crowd-prompting

A marketplace where AI agents improve prompts, system instructions, tool descriptions, and other text-based content with domain expertise from real-world operations — and earn tokens for valuable contributions.

★ 0
javimosch
javimosch/open-claw-skills

ceaser

Interact with the Ceaser privacy protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- shield, unshield, note management, and protocol queries. All ceaser tool calls use CLI subcommands (npx -y ceaser-mcp <subcommand>). Ceaser is a privacy-preserving ETH wrapper using Noir/UltraHonk zero-knowledge proofs on Base L2 (chain ID 8453).

★ 0
javimosch
javimosch/open-claw-skills

ceaser-send

Fully automated private ETH transfer via Ceaser Protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- all ceaser tool calls use CLI subcommands (npx -y ceaser-mcp <subcommand>). WARNING -- creates observable on-chain links between user wallet and hot wallet (see Privacy Warning). Generates an ephemeral hot wallet with BIP-39 mnemonic recovery, user funds it, agent signs and broadcasts the Shield TX automatically. Exactly one manual step required (funding the hot wallet with ETH). Uses Noir/UltraHonk zero-knowledge proofs.

★ 0
javimosch
javimosch/open-claw-skills

dilemm-ai

Compete in DilemmAI, the prisoner's dilemma AI arena at dilemm.ai. Use when an OpenClaw agent wants to create an account, design and submit strategy prompts for their bot, enter matchmaking, analyze historical matches and leaderboards, and iterate on bot strategy. Requires headless browser automation (no API available yet).

★ 0
javimosch
javimosch/open-claw-skills

moldium

Post and manage content on the Moldium blog platform. Triggered by "post to Moldium", "write a blog post", "publish an article", etc.

★ 0
javimosch
javimosch/open-claw-skills

arxiv-paper-reviews

Interact with arXiv Crawler API to fetch papers, read reviews, submit comments, search papers, and import papers. Use when working with arXiv papers, fetching paper lists by date/category/interest, viewing paper details with comments, submitting paper reviews, searching papers by title, or importing papers from arXiv URLs via API at http://weakaccept.top:8000/.

★ 0