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"
}Look Up Users API: Check a List of IDs
Resolve up to 20,000 vendor IDs, Didit user IDs or emails to your users in one call, then list exactly those users in the order you sent them.
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"
}How it works
- Look up the list.
POST /v3/users/lookup/with your identifiers. The call only reads and answers with alookup_id, the counts and the identifiers that matched nobody. - Read the users. Pass the
lookup_idaslookupto List users. It returns only the matched users, in the order you submitted the identifiers.
Matching rules
Each identifier is matched inside your application, in this order:| Order | Matched against | Rule |
|---|---|---|
| 1 | vendor_data | Exact match |
| 2 | Didit user ID | A UUID, the didit_internal_id of the user |
| 3 | Verified email | Case-insensitive. One email can match several users, and all of them count |
- Blank entries are dropped, and duplicates are removed keeping the first.
- A request sends at most 100,000 entries. After blanks and duplicates are removed, 1 to 20,000 identifiers must remain. Either limit exceeded returns
400withcode: too_many_identifiers. - The lookup searches your application only.
Request
{
"identifiers": [
"usr_8842",
"maria.o@gmail.com",
"f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418",
"usr_7001"
]
}
Response
{
"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"
}
| Field | Description |
|---|---|
lookup_id | Pass it as lookup to List users. |
requested | Identifiers read, after blanks and duplicates were removed. |
found | Identifiers that matched at least one user. |
not_found | The identifiers that matched nobody, each with its 1-based position in the submitted, deduplicated list, so you can fix the list at its source. |
expires_at | When the result expires. |
Read the matched users
curl -X GET 'https://verification.didit.me/v3/users/?lookup=b3a6f0c2-6a2e-4c0a-9d0e-5f3c1d2a7e11&limit=200' \
-H 'x-api-key: YOUR_API_KEY'
- Users come in the order of their identifier in your list, paginated with
limitandoffset. When one email matches several users, they are listed oldest account first. - The result is kept for 24 hours, for your application only. After that,
lookupreturns404withcode: lookup_not_found: submit the list again.
Read a lookup back
GET /v3/users/lookup/{lookup_id}/ returns the same body as the lookup, plus identifiers: the list you submitted after blanks and duplicates were removed, in order.
It answers 404 with code: lookup_not_found when the lookup expired, does not exist or belongs to another application.
Errors
| Status | Meaning |
|---|---|
400 | Validation error: too_many_identifiers for more than 100,000 entries sent or more than 20,000 identifiers after clean-up, or {"identifiers": ["Add at least one identifier."]} for an empty list. |
401 | Missing or invalid x-api-key. |
403 | The key cannot read users for this application. |
404 | lookup_not_found: the lookup expired, does not exist or belongs to another application. |
429 | Rate limit exceeded. Honour Retry-After. |
Permissions
The API key needs read access to users, and the endpoint never changes data. A key without it, or a revoked key, gets403.
Key scopes are set per key in API keys; the Console’s roles and permissions decide what a person can do in the Console and are not evaluated for API traffic.
In the Console, Look up a list needs only the permission to read users.
Related
Authorizations
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.
Body
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"]
Response
The lookup was read. Use lookup_id with List users.