跳转到主要内容
POST
Python
Didit 的 Look Up Users API 可在一次调用中,将最多 20,000 个标识符解析为您应用中的用户,并告诉您哪些标识符未匹配到任何用户。 当您持有一份账户列表时(例如代付批次的收款方、合作伙伴的账户,或欺诈查询的输出结果),并且需要了解其中每个账户的验证状态,请使用此接口。

工作原理

  1. 查询列表。 调用 POST /v3/users/lookup/ 并传入您的标识符。该调用仅做读取,返回 lookup_id、计数,以及未匹配到任何用户的标识符。
  2. 读取用户。 将 lookup_id 作为 lookup 传给列出用户。它只返回匹配的用户,顺序与您提交标识符的顺序一致。

匹配规则

每个标识符都在您的应用内按以下顺序匹配:
  • 空白条目会被丢弃,重复项会被移除,并保留首次出现的条目。
  • 单次请求最多发送 100,000 个条目。去除空白和重复项后,必须剩余 1 至 20,000 个标识符。超出任一上限都会返回 400,并附带 code: too_many_identifiers。
  • 查询仅搜索您的应用。

请求

响应

读取匹配的用户

  • 用户按照其标识符在您列表中的顺序返回,并使用 limit 和 offset 分页。当一个邮箱匹配多个用户时,账户创建最早的排在前面。
  • 结果仅供您的应用使用,保留 24 小时。之后,lookup 会返回 404 和 code: lookup_not_found:请重新提交列表。

读取已提交的查询

GET /v3/users/lookup/{lookup_id}/ 返回与查询相同的响应体,另外包含 identifiers:即您提交的列表,已去除空白值和重复值,并保持原有顺序。 当查询已过期、不存在或属于其他应用时,接口返回 404,并带有 code: lookup_not_found。

错误

权限

API 密钥需要具备用户的读取权限,且该端点从不修改数据。没有此权限的密钥或已撤销的密钥会返回 403。 密钥范围按密钥分别设置,详见 API 密钥。控制台的 角色与权限 决定人员在控制台中可以执行的操作,不用于评估 API 请求。 在控制台中,查询列表 仅需要读取用户的权限。

相关内容

授权

x-api-key
string
header
必填

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is wrong, revoked or expired; 403 means no key was sent, the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

请求体

application/json
identifiers
string[]
必填

Each entry is a vendor_data value, a Didit user ID or a verified email. Send at most 100,000 entries. Blank entries are dropped and duplicates removed, keeping the first, and at most 20,000 identifiers must remain. Either limit exceeded is a 400 with code: too_many_identifiers, and an empty list is a 400 too.

Maximum array length: 100000
示例:

响应

The lookup was read. Use lookup_id with List users.

lookup_id
string<uuid>
必填

Pass it as lookup to List users.

requested
integer
必填

Identifiers read, after blanks and duplicates were removed.

found
integer
必填

Identifiers that matched at least one user.

not_found
object[]
必填
expires_at
string<date-time>
必填

When the result expires (24 hours after the lookup).

最后修改于 2026年11月20日