didit-sessions

集成 Didit 会话和工作流 API — 用于管理验证会话的中央枢纽。 当用户想要创建验证会话、设置 KYC 工作流程、创建 具有工作流 ID 的会话、检索会话结果、获取会话决策、列出会话、 删除会话、更新会话状态、批准或拒绝会话、请求重新提交、 生成 PDF 报告、在合作伙伴之间共享会话、导入共享会话、添加或删除 阻止列表中的用户，管理阻止的面孔/文档/电话/电子邮件，处理网络钩子，或 使用 Didit 实施任何端到端验证流程。 涵盖 11 个 API 端点：创建、检索、列出、删除、更新状态、生成 pdf、 共享、导入共享、阻止列表添加、阻止列表删除、阻止列表列表。

## 概述（中文）

集成 Didit 会话和工作流 API — 用于管理验证会话的中央枢纽。
当用户想要创建验证会话、设置 KYC 工作流程、创建
具有工作流 ID 的会话、检索会话结果、获取会话决策、列出会话、
删除会话、更新会话状态、批准或拒绝会话、请求重新提交、
生成 PDF 报告、在合作伙伴之间共享会话、导入共享会话、添加或删除
阻止列表中的用户，管理阻止的面孔/文档/电话/电子邮件，处理网络钩子，或
使用 Didit 实施任何端到端验证流程。
涵盖 11 个 API 端点：创建、检索、列出、删除、更新状态、生成 pdf、
共享、导入共享、阻止列表添加、阻止列表删除、阻止列表列表。

## 原文

# 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](https://business.didit.me) → 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

```python
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
```

```typescript
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)

```json
{
  "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)

```json
{
  "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)

```json
{
  "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": "..."}
  ]
}
```

```python
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.

```python
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
`