Back to Details

didit-id-document-verification

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Didit ID Verification API

Didit 身份证件验证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/standalone-apis/id-verification Feature Guide: https://docs.didit.me/core-technology/id-verification/overview Supported Documents: https://docs.didit.me/core-technology/id-verification/supported-documents-id-verification
通过提交证件正反面图片验证身份证件。执行OCR提取、MRZ解析、真实性检查和文档活体检测。
关键约束：
  • 支持格式：JPEG、PNG、WebP、TIFF
  • 单张图片最大文件大小：5MB
  • 证件四个角必须可见，全彩，无反光/阴影
  • 仅接受实时拍摄的原始照片（不支持截图、扫描件或数字副本）
覆盖范围： 4000+种证件类型，220+个国家，130+种语言。支持护照、国民身份证、驾照和居住证。
处理流程：
  1. 智能采集与证件类型检测
  2. OCR文本提取 + MRZ/条形码解析
  3. 模板匹配、安全特征验证、篡改检测
  4. 文档活体检测（识别屏幕截图、打印副本、人像篡改）
API参考文档： https://docs.didit.me/standalone-apis/id-verification 功能指南： https://docs.didit.me/core-technology/id-verification/overview 支持的证件类型： https://docs.didit.me/core-technology/id-verification/supported-documents-id-verification

Authentication

身份验证

All requests require 
x-api-key
header. Get your key from Didit Business Console → API & Webhooks, or via programmatic registration (see below).
所有请求均需携带
x-api-key
请求头。您可以从Didit商务控制台 → API与Webhooks获取密钥，或通过程序化注册获取（详见下文）。

Getting Started (No Account Yet?)

快速上手（还没有账号？）

If you don't have a Didit API key, create one in 2 API calls:
  1. Register: 
    POST https://apx.didit.me/auth/v2/programmatic/register/
    with 
    {"email": "you@gmail.com", "password": "MyStr0ng!Pass"}
  2. Check email for a 6-character OTP code
  3. Verify: 
    POST https://apx.didit.me/auth/v2/programmatic/verify-email/
    with 
    {"email": "you@gmail.com", "code": "A3K9F2"}
    → response includes 
    api_key
To add credits: 
GET /v3/billing/balance/
to check, 
POST /v3/billing/top-up/
with 
{"amount_in_dollars": 50}
for a Stripe checkout link.
See the didit-verification-management skill for full platform management (workflows, sessions, users, billing).
如果您还没有Didit API密钥，可通过2个API调用创建：
  1. 注册： 向
    POST https://apx.didit.me/auth/v2/programmatic/register/
    发送请求，参数为
    {"email": "you@gmail.com", "password": "MyStr0ng!Pass"}
  2. 查看邮箱 获取6位OTP验证码
  3. 验证： 向
    POST https://apx.didit.me/auth/v2/programmatic/verify-email/
    发送请求，参数为
    {"email": "you@gmail.com", "code": "A3K9F2"}
    → 响应结果包含
    api_key
充值方式： 调用
GET /v3/billing/balance/
查询余额，调用
POST /v3/billing/top-up/
并携带
{"amount_in_dollars": 50}
获取Stripe结账链接。
如需完整平台管理（工作流、会话、用户、账单），请查看didit-verification-management技能。

Endpoint

接口地址

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

Headers

请求头

HeaderValueRequired
x-api-key
Your API keyYes
Content-Type
multipart/form-data
Yes
请求头值是否必填
x-api-key
您的API密钥是
Content-Type
multipart/form-data
是

Request Parameters (multipart/form-data)

请求参数（multipart/form-data）

ParameterTypeRequiredDefaultConstraintsDescription
front_image
fileYes—JPEG/PNG/WebP/TIFF, max 5MBFront image of ID document
back_image
fileNo—Same as aboveBack image (when applicable)
save_api_request
booleanNo
true
—Save in Business Console Manual Checks
vendor_data
stringNo——Your identifier for session tracking
参数类型是否必填默认值约束条件描述
front_image
文件是—JPEG/PNG/WebP/TIFF，最大5MB身份证件正面图片
back_image
文件否—同上身份证件背面图片（如有需要）
save_api_request
布尔值否
true
—在商务控制台人工审核模块保存请求记录
vendor_data
字符串否——用于会话追踪的自定义标识符

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,
});
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)

响应结果（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"
}
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

状态值说明

StatusMeaning
"Approved"
Document verified successfully
"Declined"
Verification failed (see 
warnings
)
"In Review"
Requires manual review
状态含义
"Approved"
证件验证通过
"Declined"
验证失败（查看
warnings
字段）
"In Review"
需要人工审核

Error Responses

错误响应

CodeMeaningAction
400
Invalid requestCheck file format, size, parameters
401
Invalid API keyVerify 
x-api-key
header
403
Insufficient creditsTop up at business.didit.me
状态码含义操作建议
400
请求无效检查文件格式、大小及参数
401
API密钥无效确认
x-api-key
请求头
403
余额不足在business.didit.me进行充值

Response Field Reference

响应字段参考

FieldTypeDescription
status
string
"Approved"
, 
"Declined"
, 
"In Review"
document_type
string
"Passport"
, 
"Identity Card"
, 
"Driver's License"
, 
"Residence Permit"
document_number
stringDocument ID number
personal_number
stringPersonal/national ID number
first_name
, 
last_name
, 
full_name
stringExtracted name fields
date_of_birth
string
YYYY-MM-DD
age
integerCalculated age
gender
string
"M"
, 
"F"
, 
"U"
nationality
, 
issuing_state
stringISO 3166-1 alpha-3
expiration_date
, 
date_of_issue
string
YYYY-MM-DD
portrait_image
stringBase64-encoded portrait from document
mrz
objectMachine Readable Zone data
parsed_address
objectGeocoded address: 
{city, region, postal_code, country, street_1}
warnings
array
{risk, log_type, short_description, long_description}
字段类型描述
status
字符串
"Approved"
、
"Declined"
、
"In Review"
document_type
字符串
"Passport"
、
"Identity Card"
、
"Driver's License"
、
"Residence Permit"
document_number
字符串证件编号
personal_number
字符串个人/国民身份证号
first_name
, 
last_name
, 
full_name
字符串提取的姓名字段
date_of_birth
字符串
YYYY-MM-DD
格式
age
整数计算得出的年龄
gender
字符串
"M"
、
"F"
、
"U"
nationality
, 
issuing_state
字符串ISO 3166-1 alpha-3格式
expiration_date
, 
date_of_issue
字符串
YYYY-MM-DD
格式
portrait_image
字符串证件人像的Base64编码
mrz
对象机器可读区域（MRZ）数据
parsed_address
对象地理编码后的地址：
{city, region, postal_code, country, street_1}
warnings
数组格式为
{risk, log_type, short_description, long_description}

Warning Tags

警告标签

Auto-Decline (always)

自动拒绝（始终触发）

TagDescription
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
标签描述
ID_DOCUMENT_IN_BLOCKLIST
证件在黑名单中（曾被标记）
PORTRAIT_IMAGE_NOT_DETECTED
证件上未识别到人像
DOCUMENT_EXPIRED
证件已过期
DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION
该证件类型不被接受

Configurable (Decline / Review / Approve)

可配置（拒绝/审核/通过）

CategoryTags
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
分类标签
文档活体检测
SCREEN_CAPTURE_DETECTED
, 
PRINTED_COPY_DETECTED
, 
PORTRAIT_MANIPULATION_DETECTED
MRZ问题
MRZ_NOT_DETECTED
, 
MRZ_VALIDATION_FAILED
, 
MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME
数据问题
NAME_NOT_DETECTED
, 
DATE_OF_BIRTH_NOT_DETECTED
, 
DOCUMENT_NUMBER_NOT_DETECTED
, 
DATA_INCONSISTENT
重复检测
POSSIBLE_DUPLICATED_USER
信息不匹配
FULL_NAME_MISMATCH_WITH_PROVIDED
, 
DOB_MISMATCH_WITH_PROVIDED
, 
GENDER_MISMATCH_WITH_PROVIDED
地理位置
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
1. 调用POST /v3/id-verification/ → 上传front_image（如有需要同时上传back_image）
2. 若返回"Approved" → 提取first_name、last_name、date_of_birth、document_number
   若返回"Declined" → 查看warnings：
     DOCUMENT_EXPIRED → 请求用户提供有效证件
     SCREEN_CAPTURE_DETECTED → 请求用户提供实体证件的实拍照片
     MRZ_VALIDATION_FAILED → 请求用户提供更清晰的证件图片

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
1. 调用POST /v3/id-verification/ → 验证证件
2. 调用POST /v3/passive-liveness/ → 验证活体真人
3. 调用POST /v3/face-match/ → 对比自拍照与证件人像
4. 调用POST /v3/aml/ → 对提取的姓名/出生日期/国籍进行筛查
5. 所有步骤均返回Approved → 身份完全验证通过

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