User lookup API reference

A directory lists many users. A lookup resolves exactly one. When an operator already holds a single identifier, the lookup endpoints return that one user without paging through a list. The identifier can be a national ID from a KYC record, a wallet address from a transaction, or an internal user ID from a prior call. Each endpoint matches on its identifier, returns the user in a single-resource envelope, and reports a clear error when no user matches.

These endpoints are read-only. They resolve users that already exist in the active organization. They do not create users, register identities, or change KYC state. For authentication and base URL setup, see Getting started. The active organization and system context bound every lookup, as described in Organisation and system scope.

Endpoints

Each endpoint uses the single-resource envelope with data and links.self. A successful lookup returns one user object. Reading the whole organization instead is a directory concern: see Participant directory.

Look up a user by national ID

GET /api/v2/national-ids/{nationalId}/user resolves a user from the national ID recorded on their approved KYC version. The match is exact and case-sensitive, and it considers approved KYC versions only. A pending or rejected KYC version does not resolve.

curl --globoff "https://your-platform.example.com/api/v2/national-ids/AB123456/user" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": {
    "id": "usr_01HXYZ",
    "name": "Ada Lovelace",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "[email protected]",
    "role": "member",
    "wallet": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "nationalId": "AB123456",
    "country": "GB",
    "participantId": "par_01HXYZ"
  },
  "links": {
    "self": "/v2/national-ids/AB123456/user"
  }
}

This endpoint is built for unambiguous, single-user resolution. It returns one user, not a list, so it is the right call when you already hold a verified national ID and need the matching platform identity, for example to link an operator task to a known person.

Not-found and conflict behaviour

The endpoint expects exactly one match. Two outcomes report a problem rather than a user:

• No approved KYC version in the organization carries the supplied national ID. The endpoint returns 404 with error code DALP-0427. Verify the national ID value and confirm the person has a KYC version in the approved state within this organization.
• More than one user shares the same national ID on an approved KYC version. The endpoint returns a conflict response. This signals a data-integrity problem in the organization's identity records rather than a client error, because a national ID is expected to resolve to a single person.

Look up a user by wallet address

GET /api/v2/wallets/{wallet}/user resolves the user who owns a given wallet address. Supply the address in the path. The response uses the same single-user object and envelope as the national-ID lookup.

curl --globoff "https://your-platform.example.com/api/v2/wallets/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/user" \
  -H "x-api-key: YOUR_API_KEY"

Use this lookup when you hold an on-chain address, such as the counterparty of a transfer, and need the platform user behind it.

Read a user by user ID

GET /api/v2/users/{userId} reads a single user by their internal platform user ID. Use it to refresh a known user record after you already hold its ID from a previous response.

curl --globoff "https://your-platform.example.com/api/v2/users/usr_01HXYZ" \
  -H "x-api-key: YOUR_API_KEY"

Look up a user by email

GET /api/v2/users?filter[email][email protected] resolves a user from their email address. The email filter is an identity filter: it matches the full address exactly and ignores letter case. It never matches a partial address, so filter[email][email protected] does not return [email protected]. When you want a deliberate substring search instead, request it explicitly with filter[email][iLike]=....

curl --globoff "https://your-platform.example.com/api/v2/users?filter[email][email protected]" \
  -H "x-api-key: YOUR_API_KEY"

The response is the standard paginated list envelope. A resolved user arrives as the single entry in data with meta.total equal to 1; an unknown email returns an empty data array with meta.total equal to 0.

This filter is the right existence check for create-if-absent onboarding integrations. Follow three rules when you use it that way:

• Send the full email address, never a fragment. A blank filter value is rejected with 400 rather than returning the whole directory.
• Treat meta.total greater than 1 as an error and stop, rather than picking the first entry.
• Only create a user after the lookup returns meta.total equal to 0.

Text filters on other list fields, such as name, keep case-insensitive substring matching as their shorthand default. Identity fields, email and nationalId, match exactly. Each filter parameter's description in the OpenAPI reference names its shorthand operator.

The user object

Every lookup returns the same user shape. The fields most relevant to identity resolution are:

Access scope

These lookups require the system user-read permission for the active system, the same read scope that backs the platform's user directory. A caller without that permission cannot resolve users through these endpoints. Scope every call to the organization and system the user belongs to, as covered in Organisation and system scope.

When to use it

Use these endpoints when you need to:

• Resolve a single user from a verified national ID, for example to tie an operator task to a known person.
• Find the platform user behind a wallet address seen in a transaction.
• Re-read a known user record by its internal user ID.

To list and filter many users at once instead of resolving one, see Participant directory. To read aggregate counts across users, see User statistics. To act on a member's sessions, MFA, or password, see User security administration.