Skip to main content
POST
Python
Didit’s Look Up Users API resolves a list of up to 20,000 identifiers to the users of your application in one call, and tells you which identifiers matched nobody. Use it when you hold a list of accounts, such as the payees of a payout batch, the accounts of a partner or the output of a fraud query, and you need the verification status of each one.

How it works

  1. Look up the list. POST /v3/users/lookup/ with your identifiers. The call only reads and answers with a lookup_id, the counts and the identifiers that matched nobody.
  2. Read the users. Pass the lookup_id as lookup to 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:
  • 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 400 with code: too_many_identifiers.
  • The lookup searches your application only.

Request

Response

Read the matched users

  • Users come in the order of their identifier in your list, paginated with limit and offset. 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, lookup returns 404 with code: 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

Permissions

The API key needs read access to users, and the endpoint never changes data. A key without it, or a revoked key, gets 403. 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.

Authorizations

x-api-key
string
header
required

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

application/json
identifiers
string[]
required

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
Example:

Response

The lookup was read. Use lookup_id with List users.

lookup_id
string<uuid>
required

Pass it as lookup to List users.

requested
integer
required

Identifiers read, after blanks and duplicates were removed.

found
integer
required

Identifiers that matched at least one user.

not_found
object[]
required
expires_at
string<date-time>
required

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

Last modified on November 19, 2026