跳转到主要内容
POST
curl

KYC 和 KYB 支持

Didit 会解码共享 token,读取其中嵌入的 session_kind,并克隆对应类型的会话:
  • session_kind: "user":克隆用户会话,以及其关联的身份、人脸、活体检测、人脸比对、AML、位置、地址证明、电话、邮箱、数据库核验和日志记录。
  • session_kind: "business":克隆企业会话,以及其关联的登记信息核验、关键人员记录、证件、AML 筛查、电话、邮箱、位置、问卷和日志记录。
如果该 token 早于统一共享功能上线,且不包含 session_kind 字段,Didit 会为了向后兼容而默认使用 "user"。

创建的内容

  • 在您的应用中创建一个新会话,类型与原会话相同,并带有全新的 session_id、session_number 和 session_url。
  • 新会话的 shared_from_session 字段指向来源应用中的原会话。
  • 新会话的状态为原始状态(trust_review: true),或为 IN_REVIEW(trust_review: false)。
  • 如果 vendor_data 对应的实体(用户或企业)不存在,系统会自动创建该实体。

示例

响应(201 已创建):

trust_review 参数

错误

幂等性

对同一应用重复导入同一个 share_token,无论是用户会话还是企业会话,都会被拒绝并返回 403。

相关内容

授权

x-api-key
string
header
必填

您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。

请求体

application/json
share_token
string
必填

由 POST /v3/session/{sessionId}/share/ 签发的 JWT 共享 token。

示例:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

trust_review
boolean
必填

若为 true,克隆的会话将保留源会话的最终 status。若为 false,则强制置为 In Review。

示例:

false

workflow_id
string<uuid>
必填

调用方应用中工作流的 UUID。跨应用 ID 将被拒绝并返回 404。

示例:

"9f9b1234-aaaa-bbbb-cccc-1234567890ab"

vendor_data
string | null

针对克隆会话的 vendor_data 的可选覆盖值。

示例:

"user-1"

响应

会话已克隆。响应体是两种类型的 V3 决策 payload,通过 session_kind 进行区分:"user"(KYC)包含基于列表的功能块,如 id_verifications、liveness_checks、aml_screenings;"business"(KYB)包含诸如 registry_checks 和 key_people_checks 的功能块。两者均包含 shared_from_session,即源应用中原始会话的 session_id。如果 trust_review: false,克隆会话的 status 将被强制设为 In Review。

session_id
string<uuid>

会话的唯一标识符。

session_kind
enum<string>

指示这是用户验证(KYC)还是企业验证(KYB)会话的鉴别器。当为 user 时,KYC 功能数组(id_verifications、nfc_verifications、liveness_checks、face_matches、poa_verifications、document_ai_documents、database_validations 等)适用,且企业数组不存在。当为 business 时,payload 转为携带 registry_checks、document_verifications、key_people_checks 以及共享数组(aml_screenings、phone_verifications、email_verifications、ip_analyses、questionnaire_responses)。当传递 include=events 时省略:事件结构仅存在于用户会话中,因此该变体中去除了此鉴别器。

可用选项:
user,
business
shared_from_session
string<uuid> | null

对于使用 POST /v3/session/import-shared/ 克隆的会话:为源应用中原始会话的 session_id。对于所有其他会话为 null。传入 include=events 时省略。

shared_from_session_number
integer | null

当此会话是从您组织的另一个应用导入时,为源会话的 session_number。否则为 null。

session_number
integer | null

会话编号。

session_url
string<uri> | null

会话的 URL。

status
enum<string>

会话的整体生命周期状态,即汇总的工作流结果。终态值为 Approved、Declined、In Review、Expired、Kyc Expired 和 Abandoned;Not Started、In Progress、Awaiting User 和 Resubmitted 表示会话仍在工作流流转中。

可用选项:
Not Started,
In Progress,
Awaiting User,
In Review,
Approved,
Declined,
Resubmitted,
Expired,
Kyc Expired,
Abandoned
status_override
object | null

在审核员手动设置 status 时存在。当状态为自动设置时为 null。可用于区分人工审核通过与自动通过。

decision_trace
object

状态是如何达成的:由谁设置以及触发了哪些警告。

linked_records
object | null

与会话关联的其他记录的摘要。没有可显示内容时以及声明了年龄确认标准的工作流为 null。

workflow_id
string<uuid> | null

生成此会话的工作流组的稳定标识符。工作流具有多版本,该值标识工作流本身,而非特定版本。

features
string[]

为该会话配置的验证功能列表,显示名称为:ID_VERIFICATION、NFC、LIVENESS、FACE_MATCH、POA、PHONE、EMAIL_VERIFICATION、AML、IP_ANALYSIS、DATABASE_VALIDATION、QUESTIONNAIRE、AGE_ESTIMATION、FACE_SEARCH、GEOLOCATION(位置验证)(企业验证(KYB)会话使用 KYB 功能集:KYB_REGISTRY、KYB_DOCUMENTS、KYB_KEY_PEOPLE、AML、PHONE、EMAIL_VERIFICATION、IP_ANALYSIS、QUESTIONNAIRE)。使用 include=events 时,每个条目将变为对象 {feature, node_id} 而不是纯字符串,并且邮箱功能将被重命名:在事件模式下显示为 EMAIL,而不是此处使用的 EMAIL_VERIFICATION。

会话的功能。

vendor_data
string | null

会话的供应商数据。

metadata
object | null

会话的元数据。

expected_details
object | null

在创建会话时提供的预期详细信息,用于与提取的数据进行交叉比对(KYC)或预填充公司登记搜索(KYB)。原样返回所提供的键;未提供时为 null。KYC 会话包含人员字段;企业验证(KYB)会话包含 company_name、registry_country 和 registration_number。

contact_details
object | null

创建会话时提供的联系方式详情(用于通知邮件、预填的电话/邮箱验证以及沟通语言)。当既未提供邮箱也未提供电话号码时为 null。

callback
string<uri> | null

会话的回调 URL。

id_verifications
object[] | null

身份证件验证 (OCR) 报告数组,由工作流图谱中的证件步骤生成。始终为 JSON 数组 — 如果您的工作流可以运行多个证件核查(例如主要核查加上升级核查),请读取 id_verifications[0] 并进行遍历。在至少有一个证件步骤生成数据之前为 null。每一项均为完整报告,包含 node_id、功能级别 status、提取的证件字段、图像 URL、质量评分、MRZ、地址解析、跨会话匹配项以及 warnings[]。

nfc_skip_reason
enum<string> | null

NFC 芯片验证未运行的原因,只要工作流包含 NFC 步骤便会填入此字段。NFC 待处理或芯片已被实际读取时为 null。取值:USER_SKIPPED - 用户在支持 NFC 的设备上选择跳过(由 allow_nfc_skip 允许);DOCUMENT_WITHOUT_CHIP - 证件没有可读取的 NFC 芯片(非 ICAO 9303 电子证件);CHIP_CERTIFICATE_UNAVAILABLE - 涵盖证件签发周期的签发国家/地区签名证书(CSCA)不可用,因此无法验证芯片签名;DEVICE_WITHOUT_NFC - 设备报告没有 NFC 读取器;INTEGRATION_WITHOUT_NFC_ACCESS - 验证在没有原生 SDK 的情况下运行(例如在 Web 浏览器中),因而无法访问手机的 NFC 读取器;MRZ_KEY_UNAVAILABLE - 无法从证件的 MRZ 派生芯片访问密钥;JPKI_UNAVAILABLE - 证件为日本个人番号卡(My Number Card),其芯片通过 JPKI 读取,且 JPKI 在本次验证中不可用:未启用,或应用的原生 SDK 无法读取个人番号卡。

可用选项:
USER_SKIPPED,
DOCUMENT_WITHOUT_CHIP,
CHIP_CERTIFICATE_UNAVAILABLE,
DEVICE_WITHOUT_NFC,
INTEGRATION_WITHOUT_NFC_ACCESS,
MRZ_KEY_UNAVAILABLE,
JPKI_UNAVAILABLE
nfc_verifications
object[] | null

NFC / 电子护照报告数组,由工作流图谱中的 NFC 步骤生成。此字段始终为 JSON 数组,绝非单个 nfc 对象 — 如果您的工作流可以运行多次 NFC,请读取 nfc_verifications[0] 并进行遍历。在至少有一个 NFC 步骤生成数据之前为 null。每一项均为完整报告,包含 node_id、功能级别 status、chip_protocol、chip_data、authenticity(SOD + DG 完整性)、certificate_summary 以及 warnings[]。日本个人编号卡(My Number Card)通过 JPKI 而非 ICAO 9303 读取:其条目的 chip_protocol: "jpki",证明数据保存在 jpki 下,并将 ICAO 字段保留为 null。当 NFC 步骤在提供给用户之前即被绕过(无芯片证件、缺少证书、未报告 NFC 功能、MRZ 密钥无法读取、个人编号卡的 JPKI 不可用),该字段保持为 null,且 nfc_skip_reason 会说明原因;如果在步骤本身被跳过(用户点击了跳过,或扫描时读卡器不可用),仍会生成一个带有 is_nfc_skipped: true 的报告。

liveness_checks
object[] | null

活体检测报告数组,由工作流图谱中的活体检测步骤生成。始终为 JSON 数组 — 绝非单个 liveness 对象。在至少有一个活体检测步骤生成数据之前为 null。每一项均为完整报告,包含 node_id、功能级别 status、method、score、reference_image、video_url、可选的 age_estimation、跨会话 matches[] 以及 warnings[]。

face_matches
object[] | null

人脸比对报告数组,由工作流图谱中的人脸比对步骤生成。始终为 JSON 数组 — 绝非单个 face_match 对象。在至少有一个人脸比对步骤生成数据之前为 null。每一项均为完整报告,包含 node_id、功能级别 status、相似度 score、source_image、target_image 以及 warnings[]。

phone_verifications
object[] | null

电话验证报告数组 — 始终为 JSON 数组,绝非单个 phone 对象。在至少有一个电话步骤生成数据之前为 null。每一项均为完整报告,包含 node_id、功能级别 status、电话号码与国家/地区元数据、lifecycle[]、matches[] 以及 warnings[]。

email_verifications
object[] | null

邮箱验证报告数组 — 始终为 JSON 数组,绝非单个 email 对象。在至少有一个邮箱步骤生成数据之前为 null。每一项均为完整报告,包含 node_id、功能级别 status、邮箱地址、数据泄露信息、lifecycle[]、matches[] 以及 warnings[]。

poa_verifications
object[] | null

地址证明(POA)报告数组 — 始终为 JSON 数组,绝非单个 poa 对象。在至少有一个 POA 步骤生成数据之前为 null。每一项均为完整报告,包含 node_id、功能级别 status、证件文件 URL、签发方、日期、解析后的地址以及 warnings[]。

document_ai_documents
object[] | null

按工作流节点分组的 Document AI 报告 — 始终为 JSON 数组,绝不是单个对象。在至少一个 Document AI 步骤生成数据之前为 null。仅在 session_kind = user 时存在。每项为一个节点组,包含聚合的 status、node_id、按证件列出的结果组成的 items[] 数组(提取的数据以配置的字段键作为键名)以及 warnings。

questionnaire_responses
object[] | null

问卷响应报告数组 — 始终为 JSON 数组,绝非单个 questionnaire 对象。在至少有一个问卷步骤生成数据之前为 null。每一项均为完整报告,包含 node_id、问卷元数据、包含表单元素的小节以及用户的回答。

bank_verifications
object[] | null

银行验证结果,每个银行验证步骤对应一项,适用于用户验证和企业验证。在步骤生成结果前为 null。每项的 method 说明账户的验证方式:open_banking(银行登录)或 account_lookup(账户核查),或是 statement 或 microdeposits 回退,如果在评估任何尝试前该人员未使用银行验证即继续,则为 none(continued_without_bank)。参见银行验证方式。

signatures
object[]

电子签名结果,针对用户验证和企业验证(KYB),每个签署人和签名步骤对应一项。仅在工作流包含电子签名步骤时存在;在签署人到达该步骤前为空数组。请参阅电子签名报告。

aml_screenings
object[] | null

AML 筛查报告数组:始终为 JSON 数组,绝不为单个 aml 对象。在至少有一个 AML 步骤生成数据之前为 null。每个条目均为完整报告,包含 node_id、功能级 status、total_hits、entity_type、hits[]、score、screened_data、is_ongoing_monitoring_enabled 以及 warnings[]。

ip_analyses
object[] | null

设备与 IP 分析报告数组 — 始终为 JSON 数组,绝非单个 ip_analysis 对象。在至少有一个 IP 分析步骤生成数据之前为 null。每一项均为完整报告,包含 node_id、功能级别 status、IP 及地理位置数据、设备指纹以及 warnings[]。具有重复 (node_id, ip_address, device_fingerprint) 的条目会在服务端去重。

geolocation_checks
object[] | null

位置验证结果数组,每个位置验证步骤对应一项:即该步骤已接受的尝试。在位置验证步骤生成数据之前为 null。同一步骤先前的尝试位于 geolocation_attempts 中。

geolocation_attempts
object[] | null

该会话中每个位置验证步骤的每次尝试,按时间正序排列。被重新提交所取代的尝试会被排除在外。如果工作流通过其响应属性隐去了 geolocation_checks,则该列表也会被隐去。

database_validations
object[] | null

数据库核验报告数组 — 始终为 JSON 数组,绝非单独的 database_validation 对象。在至少有一个数据库核验步骤生成数据之前为 null。每一项均为完整报告,包含 node_id、功能级别的 status、screened_data、按服务划分的 validations[](各项均包含其登记机构的 source_data)以及 warnings[]。screened_data 和 source_data 字段因国家/地区而异:

ARG(阿根廷):screened_data: {document_number, selfie, gender, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, date_of_birth, date_of_death, tax_id, tax_id_type, face_match_score, sit_1_since, banks, last_position, highest_position, rejected_checks}。使用 RENAPER 生物识别人脸比对核验。当证件(例如驾照)中未包含性别时,会通过人脸分析或名字自动推断性别

BOL(玻利维亚):screened_data: {document_number, date_of_birth, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, date_of_birth, gender}

BRA(巴西):screened_data: {tax_number, first_name, last_name, date_of_birth}。对于成功的 CPF 匹配,source_data 始终包含 {identification_number, first_name, last_name, date_of_birth, lgpd_minor, minor_under_18, minor_under_16}。成功的成年人查询会将这些标志设置为 false。Receita Federal Consulta CPF 服务可能会返回 HTTP 422(未满 18 岁未成年人)或 451(未满 16 岁)并附带因 LGPD 而不提供的数据;在这些情况下,source_data 会相应地将未成年人标志设置为 true,包含上游 HTTP 状态,且字段级核验为 no_match。有关完整代码列表,请参阅数据库核验结果代码参考中的巴西部分。

CHL(智利):screened_data: {personal_number, first_name, last_name, date_of_birth}。source_data: {identification_number, first_name, last_name, date_of_birth, gender}

COL(哥伦比亚):screened_data: {document_number, document_type, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, date_of_birth, document_type}

CRI(哥斯达黎加):screened_data: {personal_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name}

DOM(多米尼加共和国):screened_data: {personal_number}。source_data: {identification_number}(仅返回有效/无效)

ECU(厄瓜多尔):screened_data: {personal_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, street, formatted_address, gender, nationality, education, marital_status, spouse, mother_name, father_name, profession}

ESP(西班牙):screened_data: {personal_number, document_type, expiration_date, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, document_type, expiration_date}

GTM(危地马拉):screened_data: {document_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name}

HND(洪都拉斯):screened_data: {document_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name}

MEX(墨西哥):screened_data: {personal_number (CURP), first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, date_of_birth, gender, nationality, curp_status, state_of_birth, doc_probatorio, registration_year, registration_state, registration_municipality, num_acta, crip, issuing_state_code, foreign_registry_number, folio_carta, folio_certificado}。使用 RENAPO 民事登记处。对于 MEX,还提供单独的 INE 有效性检查服务作为额外的逐一核验。

PAN(巴拿马):screened_data: {personal_number, selfie}。source_data: {identification_number}。使用 SIB 生物识别核验

PER(秘鲁):screened_data: {personal_number (DNI), first_name, last_name}。source_data: {identification_number, first_name, last_name, paternal_name, maternal_name, verification_number, verification_letter}

PRY(巴拉圭):screened_data: {document_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name}

SLV(萨尔瓦多):screened_data: {document_number, date_of_birth, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name}

URY(乌拉圭):screened_data: {personal_number, date_of_birth, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name}

VEN(委内瑞拉):screened_data: {document_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, gender, date_of_birth, document_type}

database_validation_not_performed_reason
object | null

已配置的数据库核验未产生结果的原因,格式为 {code, message} 加上上下文字段。仅在包含该步骤的工作流中 database_validations 为 null 时存在,以便您能够区分“登记机构核对一致”与“未运行任何核验”。其他情况下为 null。

reviews
object[]
assignee
object | null

会话所分配到的控制台审核员,未分配给任何人时为 null。

waiting_since
string<date-time> | null

会话开始等待审核的时间。除非会话为 In Review 且您的应用设置了审核截止期限,否则为 null。

sla_due_at
string<date-time> | null

审核截止时间。除非会话为 In Review 且您的应用设置了审核截止期限,否则为 null。

created_at
string<date-time>

会话创建时的时间戳(ISO 8601,UTC)。

expires_at
string<date-time> | null

该会话计划过期的时间戳。在创建时配置了过期时间的用户验证(KYC)会话上设置(或者一旦 Approved 状态触发 KYC 过期计算)。对于未配置过期的会话以及不使用过期的类型(例如从未接收到 expires_at 的企业验证(KYB)会话)为 null。

registry_checks
object[] | null

公司登记核验。仅在 session_kind = business 时存在。每一项都封装了完整的公司登记 payload。

key_people_checks
object[] | null

汇总的关键人员核验。仅在 session_kind = business 时存在。每个条目均使用双分组格式(registry、submitted、ubo_kyc_summary)。

document_verifications
object[] | null

按工作流节点分组的证件验证检查。仅在 session_kind = business 时提供。

environment
enum<string>

会话是由生产环境应用(live)还是沙盒应用(sandbox)创建。沙盒会话是免费且完全模拟的,绝不会扣除额度。

可用选项:
live,
sandbox
sandbox_scenario
string | null

创建会话时使用的沙盒场景。对于生产环境会话以及创建时未指定场景的沙盒会话,该值为 null。

resubmissions
object[]

仅在携带 include=resubmissions 时返回,适用于用户和企业会话。每次重新提交请求对应一个条目,按最早优先排序。每个条目都包含重新提交步骤在请求之前返回的结果,因此早期的提交内容仍可读取。删除会话将删除所有提交记录。

会话在进行人脸采集前是否要求明确的生物识别同意、原因以及答复凭据。仅适用于用户验证(KYC)会话;该对象同样包含在会话 Webhook 的 decision 中。若会话从未经过评估(例如不含人脸采集的工作流),则为 null。未记录值的字段为 null。低于 4.10.0 的原生 SDK,或未上报版本的原生 SDK,无法显示同意步骤:其人脸采集将照常运行,而需要同意的会话随后将报告 status: "pending" 及 reason: "BIOMETRIC_CONSENT_UNSUPPORTED_SDK"。请参阅 生物识别同意。

investigator
object | null

该项最新的调查员审核结果,若从未审核过则为 null。由 V3 会话和企业会话决策携带(并通过 status.updated Webhook 发送)。

biometric_retention
object

此会话的实时生物特征数据被删除的时间。

fraud_check
object | null

Fraud Check API 调用的结果。对于所有其他会话均为 null。

full_session_video
string<uri> | null

完整会话录屏的会过期 URL。仅当您的组织录制完整会话视频时返回。

full_session_video_recorded_at
string<date-time> | null

录制完整会话的时间。仅在您的组织录制完整会话视频时返回。

最后修改于 2026年11月7日