didit-id-verification

TotalClaw 作者 totalclaw v1.2.0

集成 Didit ID Verification 独立 API 以验证身份文件。当用户想要验证身份证、护照、驾驶执照、居住证、或使用 Didit 的身份证明文件，或提及身份验证、文件验证， OCR 提取、MRZ 解析、KYC 文档检查或文档真实性验证。支持 220 多个国家/地区的 4000 多种文档类型。

安装 / 下载方式

TotalClaw CLI推荐

totalclaw install totalclaw:totalclaw~rosasalberto-didit-id-verification

cURL直接下载，无需登录

curl -fsSL https://skills.taituai.com/api/skills/totalclaw%3Atotalclaw~rosasalberto-didit-id-verification/file -o rosasalberto-didit-id-verification.md

## 概述（中文）

集成 Didit ID Verification 独立 API 以验证身份文件。
当用户想要验证身份证、护照、驾驶执照、居住证、
或使用 Didit 的身份证明文件，或提及身份验证、文件验证，
OCR 提取、MRZ 解析、KYC 文档检查或文档真实性验证。
支持 220 多个国家/地区的 4000 多种文档类型。

## 原文

# Didit ID Verification API

## Overview

Verifies identity documents by submitting images of the front and back sides. Performs OCR extraction, MRZ parsing, authenticity checks, and document liveness detection.

**Key constraints:**
- Supported formats: **JPEG, PNG, WebP, TIFF**
- Maximum file size: **5MB** per image
- All document corners must be visible, full-color, no glare/shadows
- Original real-time photos only (no screenshots, scans, or digital copies)

**Coverage:** 4,000+ document types, 220+ countries, 130+ languages. Supports passports, national ID cards, driver's licenses, and residence permits.

**Processing pipeline:**
1. Intelligent capture & document type detection
2. OCR text extraction + MRZ/barcode parsing
3. Template matching, security feature validation, tamper detection
4. Document liveness (detects screen captures, printed copies, portrait manipulation)

**API Reference:** https://docs.didit.me/reference/id-verification-standalone-api

---

## Authentication

All requests require `x-api-key` header. Get your key from [Didit Business Console](https://business.didit.me) → API & Webhooks.

---

## Endpoint

```
POST https://verification.didit.me/v3/id-verification/
```

### Headers

| Header | Value | Required |
|---|---|---|
| `x-api-key` | Your API key | **Yes** |
| `Content-Type` | `multipart/form-data` | **Yes** |

### Request Parameters (multipart/form-data)

| Parameter | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `front_image` | file | **Yes** | — | JPEG/PNG/WebP/TIFF, max 5MB | Front image of ID document |
| `back_image` | file | No | — | Same as above | Back image (when applicable) |
| `save_api_request` | boolean | No | `true` | — | Save in Business Console Manual Checks |
| `vendor_data` | string | No | — | — | Your identifier for session tracking |

### Example

```python
import requests

response = requests.post(
    "https://verification.didit.me/v3/id-verification/",
    headers={"x-api-key": "YOUR_API_KEY"},
    files={
        "front_image": ("front.jpg", open("front.jpg", "rb"), "image/jpeg"),
        "back_image": ("back.jpg", open("back.jpg", "rb"), "image/jpeg"),
    },
    data={"vendor_data": "user-123"},
)
```

```typescript
const formData = new FormData();
formData.append("front_image", frontImageFile);
formData.append("back_image", backImageFile);
formData.append("vendor_data", "user-123");

const response = await fetch("https://verification.didit.me/v3/id-verification/", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY" },
  body: formData,
});
```

### Response (200 OK)

```json
{
  "request_id": "a1b2c3d4-...",
  "id_verification": {
    "status": "Approved",
    "document_type": "Identity Card",
    "document_number": "YZA123456",
    "personal_number": "X9876543L",
    "first_name": "Elena",
    "last_name": "Martínez Sánchez",
    "full_name": "Elena Martínez Sánchez",
    "date_of_birth": "1985-03-15",
    "age": 40,
    "gender": "F",
    "nationality": "ESP",
    "issuing_state": "ESP",
    "issuing_state_name": "Spain",
    "expiration_date": "2030-08-21",
    "date_of_issue": "2020-08-21",
    "address": "Calle Mayor 10, Madrid",
    "formatted_address": "Calle Mayor 10, 28013 Madrid, Spain",
    "place_of_birth": "Valencia",
    "portrait_image": "<base64>",
    "front_document_image": "<base64>",
    "back_document_image": "<base64>",
    "mrz": {
      "surname": "MARTINEZ SANCHEZ",
      "given_name": "ELENA",
      "document_type": "I",
      "document_number": "YZA123456",
      "country": "ESP",
      "nationality": "ESP",
      "birth_date": "850315",
      "expiry_date": "300821",
      "sex": "F"
    },
    "parsed_address": {"city": "Madrid", "region": "...", "postal_code": "28013", "country": "ES"},
    "warnings": []
  },
  "created_at": "2025-05-01T13:11:07.977806Z"
}
```

### Status Values

| Status | Meaning |
|---|---|
| `"Approved"` | Document verified successfully |
| `"Declined"` | Verification failed (see `warnings`) |
| `"In Review"` | Requires manual review |

### Error Responses

| Code | Meaning | Action |
|---|---|---|
| `400` | Invalid request | Check file format, size, parameters |
| `401` | Invalid API key | Verify `x-api-key` header |
| `403` | Insufficient credits | Top up at business.didit.me |

---

## Response Field Reference

| Field | Type | Description |
|---|---|---|
| `status` | string | `"Approved"`, `"Declined"`, `"In Review"` |
| `document_type` | string | `"Passport"`, `"Identity Card"`, `"Driver's License"`, `"Residence Permit"` |
| `document_number` | string | Document ID number |
| `personal_number` | string | Personal/national ID number |
| `first_name`, `last_name`, `full_name` | string | Extracted name fields |
| `date_of_birth` | string | `YYYY-MM-DD` |
| `age` | integer | Calculated age |
| `gender` | string | `"M"`, `"F"`, `"U"` |
| `nationality`, `issuing_state` | string | ISO 3166-1 alpha-3 |
| `expiration_date`, `date_of_issue` | string | `YYYY-MM-DD` |
| `portrait_image` | string | Base64-encoded portrait from document |
| `mrz` | object | Machine Readable Zone data |
| `parsed_address` | object | Geocoded address: `{city, region, postal_code, country, street_1}` |
| `warnings` | array | `{risk, log_type, short_description, long_description}` |

---

## Warning Tags

### Auto-Decline (always)

| Tag | Description |
|---|---|
| `ID_DOCUMENT_IN_BLOCKLIST` | Document in blocklist (previously flagged) |
| `PORTRAIT_IMAGE_NOT_DETECTED` | No portrait found on document |
| `DOCUMENT_EXPIRED` | Document expiration date has passed |
| `DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Document type not accepted |

### Configurable (Decline / Review / Approve)

| Category | Tags |
|---|---|
| **Document liveness** | `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED` |
| **MRZ issues** | `MRZ_NOT_DETECTED`, `MRZ_VALIDATION_FAILED`, `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` |
| **Data issues** | `NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`, `DOCUMENT_NUMBER_NOT_DETECTED`, `DATA_INCONSISTENT` |
| **Duplicates** | `POSSIBLE_DUPLICATED_USER` |
| **Expected mismatch** | `FULL_NAME_MISMATCH_WITH_PROVIDED`, `DOB_MISMATCH_WITH_PROVIDED`, `GENDER_MISMATCH_WITH_PROVIDED` |
| **Geolocation** | `DOCUMENT_COUNTRY_MISMATCH` |

---

## Common Workflows

### Basic ID Verification

```
1. POST /v3/id-verification/ → front_image (+ back_image if applicable)
2. If "Approved" → extract first_name, last_name, date_of_birth, document_number
   If "Declined" → check warnings:
     DOCUMENT_EXPIRED → ask for valid document
     SCREEN_CAPTURE_DETECTED → ask for real photo of physical document
     MRZ_VALIDATION_FAILED → ask for clearer image
```

### Full Identity Verification Pipeline

```
1. POST /v3/id-verification/ → verify document
2. POST /v3/passive-liveness/ → verify real person
3. POST /v3/face-match/ → compare selfie to document portrait
4. POST /v3/aml/ → screen extracted name/DOB/nationality
5. All Approved → fully verified identity
```

---

## Utility Scripts

```bash
export DIDIT_API_KEY="your_api_key"

python scripts/verify_id.py front.jpg
python scripts/verify_id.py front.jpg back.jpg --vendor-data user-123
```

---

## 中文说明

# Didit ID Verification API

## Overview

通过提交身份文件正面和背面的图像来验证身份文件。执行 OCR 提取、MRZ 解析、真实性检查和文档活体检测。

**关键约束：**
- 支持的格式：**JPEG、PNG、WebP、TIFF**
- 每张图像最大文件大小：**5MB**
- 文档四角必须全部可见、全彩、无眩光/阴影
- 仅限原始实时拍摄的照片（不接受屏幕截图、扫描件或数字副本）

**覆盖范围：** 4000 多种文档类型、220 多个国家/地区、130 多种语言。支持护照、身份证、驾驶执照和居住证。

**处理流程：**
1. 智能采集与文档类型检测
2. OCR 文本提取 + MRZ/条形码解析
3. 模板匹配、安全特征验证、篡改检测
4. 文档活体检测（检测屏幕截图、打印副本、人像篡改）

**API Reference：** https://docs.didit.me/reference/id-verification-standalone-api

---

## Authentication

所有请求都需要 `x-api-key` 标头。从 [Didit Business Console](https://business.didit.me) → API & Webhooks 获取你的