跳转到主要内容
POST
curl
向名单中添加一个条目。该值会根据名单的条目类型进行验证:
  • 邮箱:有效的电子邮件地址
  • 电话:有效的国际电话号码,以 E.164 格式存储(例如 +14155552671)
  • ip_address:有效的 IP 地址或 CIDR 范围(例如 192.168.1.1 或 10.0.0.0/8)
  • device_fingerprint:至少 8 个字符,由字母、数字以及 -、_、: 和 . 组成。黑名单会拒绝被多台不同设备上报过的指纹,因为屏蔽该指纹会误拒无关的人。
  • 国家/地区:有效的 ISO 3166-1 alpha-3 国家/地区代码(例如 USA、GBR、ESP)。接受 alpha-2 代码(例如 US),并会自动转换为 alpha-3。
  • 用户、企业:用户或企业的 vendor_data
  • 人脸、证件、wallet_address、bank_account、密钥:任何非空字符串
所有条目值都不区分大小写。您发送的值会在存储时规范化(电话号码转为 E.164 格式,国家/地区代码转为大写,其他内容转为小写),并在验证时不区分大小写地进行匹配。例如,屏蔽 User@Example.COM 也会拦截 user@example.com。名单中每个值只保存一次,添加名单中已存在的值会返回 400。
对于人脸,如果您只有图片,请使用上传人脸;如果要获取现有会话中的人脸,请发送 reference_session_id。人脸条目需要已存储的人脸用于比对,而手动输入的 value 无法提供这一点。

从会话添加

提供 reference_session_id 时,Didit 会执行以下操作:
  1. 查找该会话(会话必须属于同一应用)
  2. 从会话中该名单条目类型的最近一条记录读取值:
    • 人脸:活体检测自拍照中的人脸;value 为人脸 UUID
    • 证件:证件号码;姓名、签发地、证件类型、地区和证件号码存储在 metadata 中,display_label 默认为持有人的姓名和证件号码
    • 电话:电话号码
    • 邮箱:电子邮件地址
    • ip_address:会话的 IP 地址
    • device_fingerprint:能够标识单一设备的指纹,优先选择完成过验证步骤的设备。在黑名单上,如果会话只包含设备类指纹,或会话是在多台设备上完成的,Didit 会拒绝该会话:此时请将精确的指纹作为 value 发送。
  3. 将条目关联到会话(reference_session_id)和记录(reference_object_uuid),以便追溯
在系统的人脸、证件、电话和邮箱黑名单中,该记录还会被标记为已列入黑名单,因此匹配它的新会话会被拒绝。对于其他条目类型,请同时发送 value。 如果未找到会话,或会话中不包含所请求条目类型的数据,则返回 400。

来自证件拍摄自拍照的人脸

用户拍摄证件时,前置摄像头可以为其拍摄自拍照(即身份证件验证报告中的 front_image_camera_front 和 back_image_camera_front 图片)。该人脸除了可以作为活体检测人脸外,也可以添加到人脸黑名单中:传入 face_image_source 并指定所需的图片。
  • 条目仅创建在系统人脸黑名单中,必须将 value 留空:Didit 会从会话的自拍照中获取人脸。
  • 自拍照必须包含一张清晰的人脸。否则请求返回 400,且不会添加任何内容。
  • 每张自拍照只能添加一次。条目的 metadata.face_image_source 和 metadata.reference_node_id 会说明其来源的自拍照。
  • 在包含多个身份证件验证步骤的工作流中,reference_node_id 用于选择使用哪个步骤的自拍照。默认情况下,Didit 使用包含该自拍照的最近一次身份证件验证。
  • 此后,该人脸会像其他黑名单人脸一样被检查:与每个新会话的活体检测自拍照比对,并与每个新的证件拍摄自拍照比对(参见 FRONT_CAMERA_FACE_IN_BLOCKLIST)。
  • 删除该条目会将人脸移出黑名单,之后它将不再匹配新会话。

同一会话中包含多条同类型记录

一个会话可以包含同一类型的多条记录,例如多步骤工作流中的两个电话号码。Didit 始终读取最近的一条。如果同时发送 value 和 reference_session_id,条目会存储您的 value,但仍关联到该最近的记录;在系统黑名单上,被标记的也是该记录。 如需列入较早记录中的值,请仅通过 value 添加,不要传入 reference_session_id:

引用交易、用户和企业

将交易或服务商用户/企业的数据加入黑名单时,请将实体的 UUID 作为 reference_object_uuid 传入,并在 metadata 中注明来源类型:
这样您可以在控制台中从黑名单条目返回原始交易、用户或企业。Didit 会存储您的 metadata 键,但 reference_image_url 和 front_image_url 除外,这两个键只能由 Didit 设置。对于从会话中读取的条目,Didit 会在您的键之外添加其自有的键,且 Didit 的键优先。 在系统的用户和企业黑名单上,Didit 还会将匹配的用户或企业设置为 BLOCKED:即 vendor_data 等于 value 的用户或企业,或 didit_internal_id 等于 reference_object_uuid 的用户或企业。请参见用户黑名单和企业黑名单。

授权

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。

路径参数

list_uuid
string<uuid>
必填

要添加到的列表的 UUID。对于您只有图像的人脸,请改用上传人脸至列表。

请求体

application/json

发送 value、reference_session_id 或两者。适用哪些字段取决于名单的 entry_type。

value
string

要列出的值,根据列表的 entry_type 进行验证:email 为有效的邮箱地址;phone 为有效的国际号码,以 E.164 格式存储;ip_address 为 IP 地址或 CIDR 范围(例如 10.0.0.0/8);device_fingerprint 为字母、数字、-、_、: 和 . 组成的至少 8 个字符(黑名单会拒绝多个不同设备报告过的指纹);country 为 ISO 3166-1 alpha-2 或 alpha-3 代码,以 alpha-3 格式存储;user 和 business 为 vendor_data;任何其他类型为非空字符串。除电话号码和国家/地区代码外均以小写形式存储,列表对每个值只保存一次(不区分大小写)。除非发送了 reference_session_id,否则为必填项;当 face_image_source 为证件采集时必须留空。

reference_session_id
string<uuid>

从您应用的个人验证或企业验证会话中提取值。Didit 读取该会话中名单条目类型(face、document、phone、email、ip_address 或 device_fingerprint)的最新记录,将条目链接到该会话和该记录,并为证件填充 display_label 和 metadata。对于 device_fingerprint 黑名单,仅包含设备类别指纹或在多台设备上完成的会话会被拒绝:请将精确指纹作为 value 发送。对于其他条目类型,或当会话没有此类记录时,也请发送 value;随后将存储您的 value,且条目仍会链接到该会话。

reference_object_uuid
string<uuid>

当条目并非来自会话时,其所代表记录的 UUID:交易 UUID,或用户或企业的 didit_internal_id。与 metadata.reference_type 配合使用。当 reference_session_id 提供了记录时,将被会话的记录替换。

face_image_source
enum<string>
默认值:liveness

带有 reference_session_id 的人脸名单:人脸取自该会话的哪张图像。liveness(默认值)为活体自拍照。front_image_camera_front 和 back_image_camera_front 是用户拍摄证件正面或背面时前置摄像头拍摄的自拍照:仅在系统人脸黑名单上被接受,且需带有 reference_session_id 以及空的 value。每张自拍照只能添加一次,且必须显示一张清晰的人脸。

可用选项:
liveness,
front_image_camera_front,
back_image_camera_front
reference_node_id
string | null

当 face_image_source 为证件采集时:对于具有多个节点的身份证件验证工作流,指定要使用其自拍照的身份证件验证节点。默认使用包含该图像的最新身份证件验证。若为 liveness 则会被拒绝。

Maximum string length: 100
display_label
string

便于人类阅读的标签。当为空时,Didit 会尽可能从会话中推导出一个(例如持有人姓名和证件号码)。

Maximum string length: 512
comment
string

自由文本备注,例如列入名单的原因。

metadata
object

随条目一同存储并按原样返回的自由格式 JSON。使用 reference_type 和 reference_id 以便控制台能链接回源头。reference_image_url 和 front_image_url 仅由 Didit 设置,如果您发送它们将被丢弃。对于从会话中读取的条目,Didit 的键将与您的键合并。

响应

条目已创建。

列表中的一个值。

uuid
string<uuid>
必填

条目标识符。在“删除列表条目”中用作 entry_uuid。

value
string
必填

列入名单的值:E.164 格式的电话号码、邮箱地址、证件号码、IP 地址或 CIDR 范围、设备指纹、钱包地址、银行账户、ISO 3166-1 alpha-3 国家/地区代码、vendor_data、key 名单上的任意字符串,或人脸名单上已存储人脸的 UUID。除电话号码和国家/地区代码外,您发送的值均以小写形式存储。匹配不区分大小写。

display_label
string | null
必填

便于人类阅读的标签。当您未提供时,Didit 会为从会话中获取的条目自动填充该标签(例如持有人姓名和证件号码)。

Maximum string length: 512
comment
string
必填

自由文本备注。未设置时为空字符串。

added_by
string | null
必填

添加此条目的主体:api(API 密钥)、控制台用户的邮箱地址或 console、system 或 migration(Didit 创建的条目),或者 rule(交易或监控规则操作)。

reference_session_id
string<uuid> | null
必填

该条目来源的验证会话。如果条目是按值添加的,则为 null。

reference_session_number
integer | null
必填

控制台中显示的该会话在应用范围内的编号。

reference_session_type
enum<string> | null
必填

个人验证会话为 kyc,企业验证会话为 kyb,不存在会话时为 null。

可用选项:
kyc,
kyb,
null
reference_object_uuid
string<uuid> | null
必填

该条目代表的记录:从会话中读取的人脸、证件、电话或邮箱记录,通过“向列表上传人脸”创建的人脸,或您发送的 UUID(例如交易 UUID 或用户的 didit_internal_id)。

metadata
object | null
必填

额外上下文。包含 Didit 设置的键(在此列出)并合并您在创建条目时发送的任何 metadata,按存储原样返回。无内容时为 null。

created_at
string<date-time>
必填

条目添加的时间。

最后修改于 2026年11月7日