didit-database-validation

Didit 数据库验证 API

概述

根据某个国家的权威来源（民事登记处、税务机关、选民名册或生物识别登记处）验证个人数据，并返回逐字段比对结果、逐服务结果代码和登记记录。可用于识别合成身份，以及不属于该个人的身份证号码。

定价： 按服务收费，每次查询 $0.05 起（多米尼加共和国 dom_cedula），最高 $7.00；大多数拉丁美洲国家身份证服务的价格为 $0.20（对登记处已回复的每项服务收取一次费用，包括不匹配和未找到的回复；400 拒绝请求以及来源未回复的服务免费；单独调用不提供免费额度）。这些标价有效至 2026 年 11 月 1 日，届时 Didit 将调整定价，每月 500 次免费检查将改为每月 $10 免费额度。请访问 didit.me/pricing 查看当前价格。

主要限制：

• issuing_state 使用 ISO 3166-1 alpha-3 代码（BRA、PER、ARG）。Alpha-2 代码（BR）会返回 400“Invalid issuing state”。
• 每个国家提供一个或多个服务（service_id）。如果不指定 services，则恰好运行一个默认服务。西班牙、肯尼亚、赞比亚以及大多数非拉丁美洲服务没有默认服务：请在 services 中指定。
• 必填字段取决于所选服务。缺少字段或字段格式错误时，会在调用登记处之前返回 400（不会收费）。
• 发送 JSON；如果服务需要 selfie（阿根廷 arg_renaper、巴拿马 pan_cedula_sib 及其他生物识别服务），则发送 multipart/form-data。
• 字段结果：full_match、partial_match、no_match。总体 status：Approved、Declined 或 In Review。

覆盖范围： 截至 2026-10-12，公开目录列出了 45 个国家的 123 项可用服务，另有全球（GLB）组：17 个拉丁美洲国家、西班牙、南非、肯尼亚、赞比亚、尼日利亚，以及欧洲、北美和亚太地区的身份、信用、居住和电话数据集。读取实时列表（无需 API 密钥）：

GET https://verification.didit.me/v1/organization/database-validation-countries/

返回内容为 { "<ISO3>": { "country_iso3", "country_name", "region", "services": [ { "service_id", "service_name", "coverage", "default_price_usd", "required_fields", "requires_any_fields", "optional_fields", "requires_consent", "requires_onboarding", "supports_selfie", ... } ] } }。对于 requires_onboarding: true 的服务，在 Didit 支持团队为你的组织启用之前会返回 400。

API 参考： https://docs.didit.me/standalone-apis/database-validation 功能指南： https://docs.didit.me/core-technology/database-validation/overview 支持的国家： https://docs.didit.me/core-technology/database-validation/database-validation-supported-countries 各项服务价格： https://docs.didit.me/getting-started/database-validation-pricing

---

身份验证

每个请求都需要 x-api-key 标头。请使用 Didit Business Console 中 Developers > API keys 下的应用 API 密钥，或以编程方式创建账户和密钥（参见入门指南）。具有自定义访问权限的命名密钥需要 Sessions 写入权限才能运行独立检查；仅限部分工作流或仅限已批准会话的密钥无法运行这些检查。

入门指南（还没有账户？）

如果你没有 Didit API 密钥，可通过 2 次 API 调用创建一个：

1. 注册： 使用 {"email": "[email protected]", "password": "MyStr0ng!Pass"} 调用 POST https://apx.didit.me/auth/v2/programmatic/register/
2. 查收邮件，获取 6 位验证码
3. 验证： 使用 {"email": "[email protected]", "code": "A3K9F2"} 调用 POST https://apx.didit.me/auth/v2/programmatic/verify-email/。密钥位于响应中的 application.api_key。

添加额度： 使用 GET /v3/billing/balance/ 查看余额；使用 POST /v3/billing/top-up/ 和 {"amount_in_dollars": 50} 获取 Stripe 结账链接。

完整的平台管理说明（工作流、会话、用户、账单）请参阅 didit-verification-management 技能。

---

端点

POST https://verification.didit.me/v3/database-validation/

请求头

请求头	值	必填
x-api-key	你的 API 密钥	是
Content-Type	application/json；发送 selfie 时使用 multipart/form-data	是

请求体

参数	类型	必填	描述
issuing_state	string	是	注册机构所在国家/地区的 ISO 3166-1 alpha-3 代码（BRA、ESP、COL）
services	array of strings	否	要运行的 service_id（例如 ["bra_cpf"]）；也接受逗号分隔或 JSON 编码的字符串。省略或留空时，只运行一个默认服务（见表格）。发送此参数会在响应中添加 services_used 和 match_score。每个 ID 都必须对 issuing_state 有效
identification_number	string	否	快捷参数，用于填充相应国家/地区的号码字段（见表格），适用于 ARG、BOL、BRA、CHL、COL、CRI、DOM、ECU、GTM、HND、MEX、PAN、PER、PRY、SLV、URY、VEN。不会覆盖显式指定的字段；其他国家/地区会忽略此参数
document_number	string	视情况而定	ARG、BOL、GTM、HND、PRY、SLV、VEN 的号码字段
personal_number	string	视情况而定	CHL、COL、CRI、DOM、ECU、MEX、PAN、PER、URY 的号码字段
tax_number	string	视情况而定	BRA 的号码字段（CPF）
national_id	string	视情况而定	KEN、ZMB、ZAF 及其他市场服务的国家 ID 号码；ESP esp_dni 可选
first_name / last_name	string	视情况而定	用于比对的姓名；某些服务必填
middle_name / full_name	string	否	某些服务会使用（某些服务使用 full_name，而非名字和姓氏）
date_of_birth	string	视情况而定	YYYY-MM-DD
date_of_issue	string	视情况而定	证件签发日期 YYYY-MM-DD；COL col_cedula 必填
expiration_date	string	否	证件有效期至 YYYY-MM-DD
document_type	string	否	P、DL、ID、RP、SSC、HIC、WP、TC、VISA、PSC、BC、OTHER
gender	string	视情况而定	M、F 或 X；arg_renaper 和 arg_renaper_data 必填
nationality	string	视情况而定	ISO 3166-1 alpha-3；COL col_migracion 必填
address	object or string	视情况而定	{"street_1", "street_2", "city", "region", "postal_code", "country"} 或一行完整地址。地址服务必填（ESP esp_dni 至少需要街道和邮政编码）
address_element_1 至 address_element_5、postal_code	string	否	分别发送的地址部分：街道、单元、城市/地区、州/地区、邮政编码（postal_code 是 element 5 的别名）
selfie	file	视情况而定	仅限 Multipart。支持 jpg、jpeg、png、webp，最大 2 MB。生物识别服务必填
consent	boolean	视情况而定	默认值为 false。对于 requires_consent 为真值的服务（例如 esp_dni），必须设为 true；否则返回 400 和 services_requiring_consent
partial_match_action	string	否	DECLINE 或 NO_ACTION（默认值为 NO_ACTION：部分匹配仍为 Approved）
no_match_action	string	否	DECLINE（默认值）或 NO_ACTION
save_api_request	boolean	否	默认值为 true：作为会话存储（Business Console、GET /v3/session/{sessionId}/decision/，并通过 request_id 和 status.updated webhook 通知），且 validations 是按服务划分的数组。设为 false：不存储任何内容，validations 是一个合并后的字段映射
vendor_data	string	否	你的用户标识符；会在响应中原样返回
metadata	object	否	存储并原样返回的自由格式 JSON
validation_type	string	否	已弃用并忽略
特定服务使用的其他标识符：passport_number、passport_expiration_date、passport_issue_country、passport_file_number、driver_license_number、driver_license_card_number、driver_license_state、driver_license_version、medicare_card_number、immi_card_number、immi_card_expiry_date、citizenship_certificate_number、birth_registration_number、birth_registration_date、birth_registration_state、marriage_certificate_number、change_of_name_certificate_number、first_partner_name、last_partner_name、voter_id、epic_card、pan、cic、identificador_ciudadano、ocr、voter_number、emission_number、bvn、bank_card_number、ssn、phone、landline、email、country_of_residence。目录中的 required_fields / requires_any_fields 会说明服务需要哪些字段。

**沙盒：**沙盒 API 密钥会跳过注册查询和计费，并返回固定的 full_match 响应（其中始终包含 services_used 和 match_score: 100，因此不要用它来测试实际响应的格式）。

示例

import requests

response = requests.post(
    "https://verification.didit.me/v3/database-validation/",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "issuing_state": "BRA",
        "services": ["bra_cpf"],
        "tax_number": "12345678900",
        "date_of_birth": "1980-01-01",
        "first_name": "John",
        "last_name": "Doe",
        "vendor_data": "user-1234",
    },
    timeout=60,
)
print(response.status_code, response.json())

// Biometric service: multipart with a selfie (Argentina RENAPER)
const form = new FormData();
form.append("issuing_state", "ARG");
form.append("services", "arg_renaper");
form.append("document_number", "12345678");
form.append("gender", "F");
form.append("first_name", "Jane");
form.append("last_name", "Doe");
form.append("selfie", selfieFile); // jpg/jpeg/png/webp, max 2 MB

const response = await fetch("https://verification.didit.me/v3/database-validation/", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY" },
  body: form,
});
const data = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${JSON.stringify(data)}`);
console.log(data.database_validation.status, data.database_validation.match_type);

响应（200 OK）

{
  "request_id": "b3e7c1a2-9d4f-4f0b-8a6c-5e2d1f0a9b3e",
  "database_validation": {
    "status": "Approved",
    "issuing_state": "BRA",
    "validation_type": "one_by_one",
    "screened_data": {
      "tax_number": "12345678900",
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1980-01-01"
    },
    "match_type": "full_match",
    "validations": [
      {
        "service_id": "bra_cpf",
        "service_name": "Brazil - CPF status check",
        "validation": {
          "full_name": "full_match",
          "date_of_birth": "full_match",
          "identification_number": "full_match"
        },
        "outcome_code": "MATCH",
        "outcome_detail": "200",
        "source_data": {
          "identification_number": "12345678900",
          "first_name": "JOHN",
          "last_name": "DOE",
          "date_of_birth": "1980-01-01",
          "lgpd_minor": false,
          "minor_under_16": false,
          "minor_under_18": false
        }
      }
    ],
    "warnings": [],
    "services_used": ["bra_cpf"],
    "match_score": 1.0
  },
  "vendor_data": "user-1234",
  "metadata": null,
  "created_at": "2026-10-12T10:30:00.000000+00:00"
}

当 save_api_request=false 时，validations 会改为合并后的映射，例如 {"full_name": "full_match", "date_of_birth": "full_match", "identification_number": "full_match"}。

状态值与处理方式

状态	含义	操作
"Approved"	full_match，或其操作为 NO_ACTION 的 partial_match / no_match（默认情况下，partial match 的操作为 NO_ACTION）	继续；仍需查看 warnings 和 errors
"Declined"	某条警告被判定为 DECLINE：no_match 或已被替代的证件（no_match_action，默认值为 DECLINE），或者操作为 partial_match_action=DECLINE 的 partial match	身份数据与注册记录不匹配
"In Review"	仅适用于 COULD_NOT_PERFORM_DATABASE_VALIDATION：服务已响应，但无法确认任何信息（例如，唯一的服务返回了 INCONCLUSIVE 或 REGISTRY_UNAVAILABLE）	手动审核或稍后重试

拒绝优先于审核。多服务请求中，一个服务可能为 Approved，而另一个服务失败：务必检查 errors[] 和每个 outcome_code。

错误响应

Code	Meaning	Action
400	请求无效	查看响应正文中的字段错误
401	API 密钥已过期	在 Developers > API keys 中轮换密钥或创建新密钥
403	API 密钥缺失、错误或已撤销；未获准访问此端点的受限密钥；请求来自密钥 IP 允许列表之外；或额度不足	查看 detail 或 error 中的消息：修正 x-api-key 标头或密钥的访问权限，或充值
429	速率限制：每个密钥每分钟最多 300 个 POST/PATCH/DELETE 请求和 600 个 GET 请求	等待 Retry-After 指定的秒数，然后重试
502	未选中的服务返回可用结果。正文：error 加上 validation_errors[]（service_id、code，例如 empty_provider_response、message、retryable: true）。不会计费	稍后重试；使用 save_api_request=true 时，仍会将此尝试记录为会话

此端点的 400 响应正文（绝不计费）：

• {"error": ["Invalid issuing state. Valid options are: ARE, ARG, ..."]}：issuing_state 错误或使用了 alpha-2 代码
• {"error": ["No database validation services configured for ESP."]}：该国家/地区没有默认服务；请发送 services
• {"error": ["Missing required fields: tax_number (or use 'identification_number' ...)"], "fields_required_by": {"tax_number": ["bra_cpf"]}}；对于同类问题，也可能包含 any_field_required_by、field_dependencies_required_by、address_fields_required_by
• {"services": [...]}：服务 ID 未知、该服务未在该国家/地区上线，或需要先完成引导流程（requires_onboarding）
• {"consent": [...], "services_requiring_consent": [...]}：请发送 consent: true
• {"tax_number": ["Invalid tax number for BRA: Brazilian CPF (exactly 11 digits). ..."]} 或 invalid_fields_by_service：格式规则未通过
• {"error": "...", "validation_errors": [{"code": "provider_rejected_input", "retryable": false, ...}]}：所有数据源均拒绝了所提交的数据；请更正数据，使用相同值重试不会成功

额度检查会计算所选服务的价格总和，并在调用任何登记机构前执行；额度不足时，403 响应正文为 {"error": "You don't have enough credits to perform this request. ..."}。

---

响应字段参考

字段	类型	说明
request_id	uuid	当 save_api_request=true 时为会话 ID；否则为一次性关联 ID
database_validation.status	string	Approved、Declined 或 In Review
database_validation.issuing_state	string	返回 alpha-3 国家代码
database_validation.validation_type	string	one_by_one；当 2 个或更多服务完全匹配时为 two_by_two
database_validation.screened_data	object	发送给服务的输入（日期格式为 YYYY-MM-DD，selfie 为临时 URL，提供同意时为 consent_obtained: true）
database_validation.match_type	string/null	各服务的匹配情况：full_match、partial_match 或 no_match；仅返回结果的服务为 null
database_validation.validations	array or object	每项服务包含：service_id、service_name、validation（字段对应 full_match/partial_match/no_match）、outcome_code、outcome_detail、source_data（登记记录）。当 save_api_request=false 时为合并映射
database_validation.warnings	array	{feature, risk, additional_data, log_type, short_description, long_description}；完全匹配且无异常时为空
database_validation.errors	array	仅在部分服务失败时返回：service_id、code、message、retryable。这些服务不会收费
database_validation.services_used	array	返回结果的服务（仅当请求中发送了 services 时）
database_validation.match_score	number	尝试的服务中完全匹配所占的比例，范围为 0.0-1.0（仅当请求中发送了 services 时）
vendor_data / metadata	string/object	返回你提供的值
created_at	string	ISO 8601 UTC 时间戳

outcome_code 值： MATCH（匹配）、PARTIAL_MATCH（部分匹配）、NO_MATCH（不匹配，结论明确）、DOCUMENT_NOT_FOUND（登记记录中不存在该号码）、INVALID_DOCUMENT_FORMAT / INVALID_INPUT（登记机构拒绝了数据）、MINOR_BLOCKED（未成年人受限）、DECEASED（已故）、BIOMETRIC_NO_MATCH（人脸不匹配）、BIOMETRIC_IMAGE_UNUSABLE（请重新拍摄自拍照）、INCONCLUSIVE（需审核，并非不匹配）、DOCUMENT_SUPERSEDED（该证件已有更新版本）、REGISTRY_UNAVAILABLE / REGISTRY_ERROR（数据源故障，不收费）。

---

匹配逻辑

规则	行为
姓名	按姓名各部分进行模糊匹配（少量拼写错误仍可匹配：“Christophel”和“Christopher”属于完全匹配，“Chris”则不属于）
出生日期、证件号码	仅精确匹配
match_type	任一服务为 full_match 时返回 full_match；否则，任一服务为 partial_match 时返回 partial_match；否则返回 no_match
validation_type	两个或更多不同服务完全匹配时为 two_by_two；否则为 one_by_one。没有单独的 2x2 价格：每项服务均按自身价格收费
决定性字段	服务只会比较其持有的字段与您发送的字段；必填字段不一定会参与比较

---

警告标签

标签	适用情况	效果
DATABASE_VALIDATION_NO_MATCH	match_type 为 no_match，或服务给出明确的否定结果（例如 DOCUMENT_NOT_FOUND、DECEASED），且没有字段比较结果	no_match_action（默认值为 DECLINE）
DATABASE_VALIDATION_PARTIAL_MATCH	match_type 为 partial_match	partial_match_action（默认值为 NO_ACTION：information，状态保持为 Approved）
DATABASE_VALIDATION_DOCUMENT_SUPERSEDED	服务返回 DOCUMENT_SUPERSEDED：人员匹配，但存在更新版本的证件（match_type 仍可能为 full_match）	遵循 no_match_action
COULD_NOT_PERFORM_DATABASE_VALIDATION	服务已运行，但未能确认任何结果：答复不确定、数据源不可用或运行失败，或者登记机构无法使用所发送的数据。additional_data 会列出相关服务。缺失或无效字段不会出现此情况：系统会返回 400	始终为 In Review（log_type: warning）
DATABASE_VALIDATION_NOT_APPLICABLE	仅适用于工作流会话（文档不含服务所需的标识符）	此端点不会产生此结果

log_type 与操作相对应：DECLINE 对应 error，NO_ACTION 对应 information。补全缺失数据后自动重新运行的功能仅适用于工作流会话，不适用于此端点。

---

支持的国家

主要国家，数据来自公开目录和价格表（2026-10-12）。如果省略 services，则运行“默认服务”。

issuing_state	默认服务	必填字段	编号格式	覆盖率	价格	其他服务
ARG	arg_renaper（生物识别）	document_number、selfie、gender	DNI，7-8 位，可带 M/F 前缀	-	$0.20	arg_renaper_data（document_number、gender，无需自拍，$0.20）；arg_citizens $1.90、arg_credit_bureau $2.15
BOL	bol_cedula	document_number、date_of_birth	CI，6-10 位	90-95%	$0.20	-
BRA	bra_cpf	tax_number、date_of_birth	CPF，恰好 11 位	~100%	$0.20	另有 9 项，例如 bra_cpf_facial（自拍、同意，$0.45）、bra_unico_idcloud（自拍、同意，$0.20）、bra_death_check、bra_tax_registration $0.15
CHL	chl_rut	personal_number	RUT，例如 12345678-9	-	$0.20	-
COL	col_cedula	personal_number、date_of_issue	Cedula，6-10 位	90-95%	$0.20	col_migracion（personal_number、date_of_birth、nationality，$1.20）
CRI	cri_cedula	personal_number	Cedula，9-12 位	90-95%	$0.20	-
DOM	dom_cedula	personal_number	Cedula，恰好 11 位	-	$0.05	-
ECU	ecu_cedula	personal_number	Cedula，恰好 10 位	-	$0.20	-
ESP	无：发送 services: ["esp_dni"] 和 consent: true	first_name、last_name、date_of_birth、address（街道 + 邮政编码）	无编号字段；也会比对可选的 national_id（DNI/NIE）	~75%	$1.26	-
GTM	gtm_dpi	document_number、date_of_birth	DPI，恰好 13 位	90-95%	$0.20	gtm_dpi_facial（document_number、selfie、同意，$0.35）
HND	hnd_dni	document_number	DNI，恰好 13 位	90-95%	$0.20	-
MEX	mex_curp	personal_number	CURP，恰好 18 个字符	~100%	$0.20	mex_ine_vigencia（INE 凭证：cic、identificador_ciudadano、ocr，或 voter_number + emission_number，$0.20）
PAN	pan_cedula_sib（生物识别）	personal_number、selfie	Cedula，5-20 个字符	-	$0.75	pan_cedula_sib_plus（相同字段，$1.50）
PER	per_dni	personal_number	DNI，恰好 8 位	-	$0.20	per_tax_registration（first_name、last_name、date_of_birth、personal_number，$1.75）
PRY	pry_cedula	document_number	CI，6-10 位	90-95%	$0.20	-
SLV	slv_dui	document_number、date_of_birth	DUI，恰好 9 位	90-95%	$0.20	-
URY	ury_cedula	personal_number、date_of_birth	CI，7-9 位	90-95%	$0.20	-
VEN	ven_cedula	document_number	Cedula，7-10 位，可带 V/E 前缀	90-95%	$0.20	-
KEN	无：ken_national_id	first_name、last_name、date_of_birth、national_id	-	~90%	$0.65	-
ZMB	无：zmb_national_id	national_id、first_name、last_name	-	-	$0.20	-
ZAF	zaf_africa_national_id	first_name、last_name、date_of_birth、national_id	-	~100%	$1.10	另有 12 项（驾照、银行账户持有人、公司注册、欺诈防范等）

其他国家（澳大利亚、奥地利、加拿大、中国、丹麦、芬兰、法国、德国、印度、印度尼西亚、意大利、柬埔寨、马来西亚、荷兰、新西兰、尼日利亚、挪威、菲律宾、新加坡、瑞典、瑞士、泰国、英国、美国）和 GLB 组：请查阅目录，并始终发送 services；其中大多数没有默认服务。可选字段（通常为 first_name、last_name）会在服务支持时增加姓名比对。

---

常见工作流

验证身份证件中的数据

1. POST /v3/id-verification/ -> id_verification.issuing_state (alpha-3), document_number,
   personal_number, first_name, last_name, date_of_birth, gender, date_of_issue
   (see the didit-id-document-verification skill)
2. Look up the country in the table (or the catalog) and pick services
3. POST /v3/database-validation/ with issuing_state, services and the required fields
   (identification_number fills the country's number field)
4. Approved -> data confirmed by the registry
   Declined -> DATABASE_VALIDATION_NO_MATCH / _DOCUMENT_SUPERSEDED: do not trust the identity data
   In Review -> COULD_NOT_PERFORM_DATABASE_VALIDATION: review or retry later
   502 -> no service answered (not billed): retry later

西班牙 DNI/NIE

{
  "issuing_state": "ESP",
  "services": ["esp_dni"],
  "consent": true,
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-01-01",
  "address": {"street_1": "Calle Mayor 10", "city": "Madrid", "postal_code": "28013", "country": "ES"}
}

生物识别数据库核验（阿根廷、巴拿马）

使用 multipart/form-data 发送请求，并附上 selfie（最大 2 MB）。arg_renaper 还需要 document_number 和 gender；pan_cedula_sib 需要 personal_number。BIOMETRIC_NO_MATCH 表示人脸确实不匹配；BIOMETRIC_IMAGE_UNUSABLE 表示需要重新拍摄自拍照。

获取已存储的结果

启用 save_api_request=true（默认值）后，GET /v3/session/{request_id}/decision/ 会在 database_validations[] 中返回结果。

---

实用脚本

validate_database.py：从命令行将身份数据与政府数据库进行核验。输出 JSON 响应，然后输出状态、匹配类型、各服务的结果、警告和错误。

# Requires: pip install requests
export DIDIT_API_KEY="your_api_key"
# issuing_state is ISO alpha-3. Use the number field the country needs (see the table) or --identification-number.
python scripts/validate_database.py --issuing-state PER --personal-number 12345678 --first-name Carlos --last-name Garcia
python scripts/validate_database.py --issuing-state BRA --tax-number 12345678900 --dob 1980-01-01 --services bra_cpf
python scripts/validate_database.py --issuing-state MEX --identification-number GARC850315HDFRRL09
python scripts/validate_database.py --issuing-state COL --personal-number 1234567890 --date-of-issue 2015-06-20
python scripts/validate_database.py --issuing-state ARG --document-number 12345678 --gender F --selfie selfie.jpg
python scripts/validate_database.py --issuing-state ESP --services esp_dni --consent --first-name John --last-name Doe \
  --dob 1990-01-01 --address '{"street_1": "Calle Mayor 10", "city": "Madrid", "postal_code": "28013", "country": "ES"}'