from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.users.lookup(
identifiers=["usr_8842", "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "usr_7001"],
)
print(result)import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.users.lookup({
identifiers: ["usr_8842", "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "usr_7001"],
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.Users.Lookup(ctx, didit.UsersLookupRequest{
Identifiers: []string{"usr_8842", "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "usr_7001"},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import java.util.List;
import me.didit.Didit;
import me.didit.types.UsersLookupRequest;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.users().lookup(UsersLookupRequest.builder()
.identifiers(List.of("usr_8842", "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "usr_7001"))
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->users->lookup([
'identifiers' => ['usr_8842', 'maria.o@gmail.com', 'f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418', 'usr_7001'],
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.users.lookup(identifiers: ["usr_8842", "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "usr_7001"])
puts result.to_husing System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Users.LookupAsync(new UsersLookupRequest
{
Identifiers = new string[] { "usr_8842", "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "usr_7001" },
});
Console.WriteLine(JsonSerializer.Serialize(result));curl --request POST \
--url https://verification.didit.me/v3/users/lookup/ \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"identifiers": [
"usr_8842",
"maria.o@gmail.com",
"f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418",
"usr_7001"
]
}
'{
"lookup_id": "b3a6f0c2-6a2e-4c0a-9d0e-5f3c1d2a7e11",
"requested": 4,
"found": 3,
"not_found": [
{
"identifier": "usr_7001",
"position": 4
}
],
"expires_at": "2026-11-19T10:30:00Z"
}查询用户 API:批量检查 ID 列表
使用 Didit 一次调用即可将最多 20,000 个供应商 ID、Didit 用户 ID 或邮箱解析为对应用户,并按您提交的顺序返回这些用户。
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.users.lookup(
identifiers=["usr_8842", "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "usr_7001"],
)
print(result)import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.users.lookup({
identifiers: ["usr_8842", "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "usr_7001"],
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.Users.Lookup(ctx, didit.UsersLookupRequest{
Identifiers: []string{"usr_8842", "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "usr_7001"},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import java.util.List;
import me.didit.Didit;
import me.didit.types.UsersLookupRequest;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.users().lookup(UsersLookupRequest.builder()
.identifiers(List.of("usr_8842", "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "usr_7001"))
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->users->lookup([
'identifiers' => ['usr_8842', 'maria.o@gmail.com', 'f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418', 'usr_7001'],
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.users.lookup(identifiers: ["usr_8842", "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "usr_7001"])
puts result.to_husing System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Users.LookupAsync(new UsersLookupRequest
{
Identifiers = new string[] { "usr_8842", "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "usr_7001" },
});
Console.WriteLine(JsonSerializer.Serialize(result));curl --request POST \
--url https://verification.didit.me/v3/users/lookup/ \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"identifiers": [
"usr_8842",
"maria.o@gmail.com",
"f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418",
"usr_7001"
]
}
'{
"lookup_id": "b3a6f0c2-6a2e-4c0a-9d0e-5f3c1d2a7e11",
"requested": 4,
"found": 3,
"not_found": [
{
"identifier": "usr_7001",
"position": 4
}
],
"expires_at": "2026-11-19T10:30:00Z"
}工作原理
- 查询列表。 调用
POST /v3/users/lookup/并传入您的标识符。该调用仅做读取,返回lookup_id、计数,以及未匹配到任何用户的标识符。 - 读取用户。 将
lookup_id作为lookup传给列出用户。它只返回匹配的用户,顺序与您提交标识符的顺序一致。
匹配规则
每个标识符都在您的应用内按以下顺序匹配:| 顺序 | 匹配对象 | 规则 |
|---|---|---|
| 1 | vendor_data | 精确匹配 |
| 2 | Didit 用户 ID | UUID,即用户的 didit_internal_id |
| 3 | 已验证邮箱 | 不区分大小写。一个邮箱可以匹配多个用户,这些用户都会计入结果 |
- 空白条目会被丢弃,重复项会被移除,并保留首次出现的条目。
- 单次请求最多发送 100,000 个条目。去除空白和重复项后,必须剩余 1 至 20,000 个标识符。超出任一上限都会返回
400,并附带code: too_many_identifiers。 - 查询仅搜索您的应用。
请求
{
"identifiers": [
"usr_8842",
"maria.o@gmail.com",
"f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418",
"usr_7001"
]
}
响应
{
"lookup_id": "b3a6f0c2-6a2e-4c0a-9d0e-5f3c1d2a7e11",
"requested": 4,
"found": 3,
"not_found": [{ "identifier": "usr_7001", "position": 4 }],
"expires_at": "2026-11-19T10:30:00Z"
}
| 字段 | 说明 |
|---|---|
lookup_id | 将其作为 lookup 传入 列出用户。 |
requested | 已读取的标识符,已去除空白项和重复项。 |
found | 至少匹配到一个用户的标识符。 |
not_found | 未匹配到任何用户的标识符。每个标识符都附有其在提交的去重列表中从 1 开始计数的 position,便于您在源头修正该列表。 |
expires_at | 结果过期的时间。 |
读取匹配的用户
curl -X GET 'https://verification.didit.me/v3/users/?lookup=b3a6f0c2-6a2e-4c0a-9d0e-5f3c1d2a7e11&limit=200' \
-H 'x-api-key: YOUR_API_KEY'
- 用户按照其标识符在您列表中的顺序返回,并使用
limit和offset分页。当一个邮箱匹配多个用户时,账户创建最早的排在前面。 - 结果仅供您的应用使用,保留 24 小时。之后,
lookup会返回404和code: lookup_not_found:请重新提交列表。
读取已提交的查询
GET /v3/users/lookup/{lookup_id}/ 返回与查询相同的响应体,另外包含 identifiers:即您提交的列表,已去除空白值和重复值,并保持原有顺序。
当查询已过期、不存在或属于其他应用时,接口返回 404,并带有 code: lookup_not_found。
错误
| 状态 | 含义 |
|---|---|
400 | 验证错误:提交的条目超过 100,000 条,或清理后的标识符超过 20,000 个时返回 too_many_identifiers;列表为空时返回 {"identifiers": ["Add at least one identifier."]}。 |
401 | 缺少 x-api-key,或其值无效。 |
403 | 该密钥无权读取此应用的用户。 |
404 | lookup_not_found:该查询已过期、不存在,或属于其他应用。 |
429 | 超出速率限制。请遵守 Retry-After。 |
权限
API 密钥需要具备用户的读取权限,且该端点从不修改数据。没有此权限的密钥或已撤销的密钥会返回403。
密钥范围按密钥分别设置,详见 API 密钥。控制台的 角色与权限 决定人员在控制台中可以执行的操作,不用于评估 API 请求。
在控制台中,查询列表 仅需要读取用户的权限。
相关内容
授权
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.
请求体
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.
100000["usr_8842", "maria.o@gmail.com"]
响应
The lookup was read. Use lookup_id with List users.