跳转到主要内容
POST
Python
提交手动输入的标识符和声明的身份属性,选择要运行的检查,并分别查看每项结果。 请先通过 规划欺诈检测 检查输入要求和预估费用。

选择配置文件

固定 profile_version,以明确所选的默认值和决策策略。 默认配置文件为 standard,版本为 2026-08-27。 版本 2026-09-14 新增可选的邮箱和电话社交信息补充,并将每次完成的检查记录为原生的用户验证会话。 在该版本中,付费附加项需要主动选择开启。 版本 2026-09-14.1 还会为 Enterprise 套餐中启用全球共享的组织启用全球欺诈网络标识符查询。 版本 2026-09-14.2 新增面向巴西的可选自拍照与 CPF 参照检查。 更早的版本保持其原有行为。 当前配置文件支持邮箱风险、电话风险、IP 风险、符合条件的数据库核验,以及您应用自身的私有网络历史记录。 基于自拍照的身份绑定需要版本 2026-09-14.2。 在更早的版本中选择该功能,会返回 not_available_in_profile_version。

声明的身份与上下文

将邮箱、电话和政府标识符放入 subject.identifiers。 政府标识符必须同时提供签发国家/地区;如果编号只在某一地区内唯一,还可能需要提供签发机构。 将姓名、出生日期、国籍和地址放入 subject.attributes。 这些内容是待比对的声明。只有所选数据源支持时才会进行比对,提交本身并不意味着它们已被验证为事实。 使用 context 提供验证尝试的地址、用户代理、用途、国家/地区,以及所需的同意声明。 这样可以将验证尝试本身的信息与当事人的信息区分开来。 对于支持的生物识别检查,请以 base64 编码的 JPEG、PNG 或 WebP 格式提供 subject.selfie,大小上限为 6 MB。 也接受对应的图像 data URI。 请勿发送参考图像、远程 URL 或存储密钥。

自拍照与声明的标识符

选择 biometric_identity,提交巴西 tax_number 标识符和自拍照,并确认 context.consent_obtained。 参照检查会判断该自拍照是否属于声明的 CPF 持有人。 缺少同意会返回 consent_required,不支持的国家/地区会返回 unsupported_region。 该模块按每次检查收费,价格基于您组织的数据库核验费率;运行前请先查看套餐。 参照检查返回结果后,identity_relationship.result 为 match、mismatch 或 inconclusive。 结果为不确定的检查需要审核,且绝不能视为不匹配。 该结果仅确定自拍照与 CPF 之间的关系。 它不验证提交的姓名或出生日期,不证明活体,也不会在互联网或全球欺诈网络中搜索人脸。 除非其他所选数据源为这些字段提供证据,否则姓名和出生日期仍然只是声明。 超时和数据源错误属于不可用结果,不计费。 已完成但结果不确定的检查,按相同的参照检查费率计费。 本检查不会将自拍照包含在结果中,也不会将其存储为会话媒体。

选择检查项

checks.include 用于选择模块,checks.exclude 优先生效。 显式传入空的 include 列表会禁用所有可选操作,但标准化步骤仍会运行。 省略 include 时,使用所固定配置文件的默认值。 邮箱和电话社交信息补充分别通过 email_social 和 phone_social 选择。 它们需要有效且匹配的标识符,并且不会发送 OTP。

分别解读结果,避免混为一谈

每个模块都会报告其执行状态、原因以及可计费单位。 not_requested、excluded_by_caller、missing_required_input 和 source_unavailable 分别描述不同的结果。 数据源缺失既不是身份不匹配,也不是零风险结果。 attribute_evidence 描述字段级证据,而 risk 将身份、联系方式、设备、行为和欺诈网络等维度分开呈现。 共享的邮箱、设备或其他标识符只是一种可观察到的关联,并不能证明两个账户属于同一个人,也不能证明存在欺诈行为。 recommendation 是该检查自身的建议,不会改变其他记录的状态。 社交信息补充的结果显示在 enrichment 下,其中不可用的结果与已完成的结果需加以区分。

全球欺诈网络

选择 networks_cross_org,即可在共享网络中查询受支持的邮箱、电话以及已正确添加命名空间的证件标识符。 该查询需要 Enterprise 套餐,并且您的组织的共享模式须设为 global。 如果不满足这两个条件,套餐会以 available: false 和 availability_reason: "entitlement_required" 报告该模块,选择了该模块的检查会被跳过,状态为 skipped,原因为 entitlement_required。 如果您的组织未启用网络功能,也会返回相同的原因。 沙盒应用不受套餐或共享模式限制:只要提供受支持的标识符,该模块就会运行并返回空的示例结果。 该查询使用组织现有的读取配额,并记录一条读取审计日志。 每次查询不单独收费。 规划检查本身不会查询共享索引,也不会消耗其读取配额。 检查完成后,network.cross_organization 包含 signals_checked 以及已披露的汇总 insights。 每条洞察包含信号类型、结果类别、贡献方数量、时间范围分组,以及仅在启用披露时才包含的行业类别。 它绝不会标识其他组织、账户、个人或验证。 低于披露阈值的结果会被省略;空列表并不能证明不存在欺诈历史。 一条已披露的共享信号只会触发审核建议,绝不会自动拒绝,也不构成身份匹配。 无法使用的查询会单独报告其原因,与已完成但结果为空的查询区分开来。 如果您的组织之后失去跨组织访问权限,例如套餐变更后,或共享模式不再为 global,则结果检索、重试和会话详情将隐藏共享汇总数据及由其推导出的风险证据。 原有建议仍作为历史决策保留;读取操作不会改变验证状态。

会话、重试与费用

check_id 通过获取欺诈检查检索已保存的结果。 存在 request_id 时,它标识其对应的原生验证会话。 版本 2026-09-14、2026-09-14.1 和 2026-09-14.2 始终会创建该会话,即使只选择了私有网络历史记录也是如此。 在检查仍然存在期间,使用相同请求正文复用 client_reference,将返回原始结果,不会再次执行或收费。 同一引用若搭配不同的请求正文,将返回 409。 如果检查仍在执行中,请在响应中 Retry-After 指定的间隔后重试同一请求。 删除关联的验证也会删除欺诈检查结果;此后检索将返回 404。 在执行过程中被删除的检查,不能发布已完成的结果。 价格取决于您组织当前的预付费或合同费率。 不可用和被跳过的模块不计费,私有网络历史记录也没有单次检查费用。 沙盒检查使用示例响应,不调用付费供应商,也不收费。

授权

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。

请求体

subject
object
必填
client_reference
string

您为此项检查指定的自身参考编号。同时充当幂等性密钥:使用相同的请求体复用该编号将返回原始检查结果,而不会再次运行模块或计费;使用不同的请求体复用该编号将返回 409。

Required string length: 1 - 255
profile
string
默认值:standard

编排配置文件 ID。默认为 Didit 的 standard 配置文件。

Required string length: 1 - 64
profile_version
string

固定冻结的档案版本。默认为档案的当前版本。

Required string length: 1 - 32
context
object
checks
object
vendor_data
string
Maximum string length: 1000
metadata
any

响应

check_id
string<uuid>
必填
client_reference
string | null
必填
processing_status
enum<string>
必填
  • pending - 等待中
  • running - 运行中
  • completed - 已完成
  • failed - 失败
可用选项:
pending,
running,
completed,
failed
profile_id
string
必填
profile_version
string
必填
created_at
string<date-time>
必填
completed_at
string<date-time> | null
必填
inputs
object[]
必填
modules
object[]
必填
attribute_evidence
object[]
必填
compound_evidence
object[]
必填
risk
object[]
必填
network
object
必填
recommendation
enum<string>
必填
  • approve - 通过
  • review - 审核
  • reject - 拒绝
可用选项:
approve,
review,
reject
next_action
enum<string>
必填
  • none - 无
  • manual_review - 人工审核
  • step_up - 强化验证
  • resubmit_capture - 重新提交采集
可用选项:
none,
manual_review,
step_up,
resubmit_capture
decision_reasons
string[]
必填
coverage
object
必填
usage
object[]
必填
request_id
string<uuid>

为此检查创建的原生验证会话。

enrichment
object
identity_relationship
object | null
vendor_data
string | null
metadata
unknown
最后修改于 2026年11月7日