Skip to main content
GET
curl
Retrieve the entries of one list, newest first, with optional search. search matches part of an entry’s value or label without regard to case; reference_session_id narrows the results to the entries taken from one verification session. On a face list, metadata.face_image_source tells which of the session’s faces each entry is (liveness when absent). Face and document entries carry image URLs in metadata that expire shortly after the call. Fetch the entries again for fresh URLs rather than storing them. An API key without media: read receives null for those URLs.

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.

Path Parameters

list_uuid
string<uuid>
required

UUID of the list, as returned by List lists or Create a list.

Query Parameters

Case-insensitive text that the entry's value or display_label must contain.

reference_session_id
string<uuid>

Only the entries taken from this person verification session, for example to see which of its faces are already listed.

limit
integer
default:50

Page size. Defaults to 50. A value above 1000000 returns 400; zero, a negative or a non-numeric value falls back to 50.

Required range: 1 <= x <= 1000000
offset
integer
default:0

Zero-based index of the first item to return. Prefer following next. A value above 1000000 returns 400; a negative or non-numeric value falls back to 0.

Required range: 0 <= x <= 1000000

Response

A page of entries, newest first.

count
integer
required

Total number of entries matching the filters.

Required range: x >= 0
next
string<uri> | null
required

Absolute URL of the next page, or null on the last page.

previous
string<uri> | null
required

Absolute URL of the previous page, or null on the first page.

results
object[]
required
Last modified on November 1, 2026