Skip to main content
POST
curl
Create a list for your application. Only allowlist and custom lists can be created: Didit provisions one system blocklist per entry type, and you add to it with Create entry. Choose entry_type carefully: it cannot be changed later, and it decides how each value is validated when you add it. See Lists for what each list type does.

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 missing, wrong, revoked or expired; 403 means 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
name
string
required

List name. Must differ from the name of every other list of the application, system lists included.

Required string length: 1 - 255
list_type
enum<string>
required

allowlist or custom. blocklist is refused with 400.

Available options:
allowlist,
custom
entry_type
enum<string>
required

What the list holds: face, document (document number), phone, email, ip_address (IP address or CIDR range), device_fingerprint, wallet_address, bank_account, country (ISO 3166-1 alpha-3), user or business (your vendor_data), or key (any string). It decides how entry values are validated and matched. Cannot be changed later.

Available options:
face,
document,
phone,
email,
ip_address,
device_fingerprint,
wallet_address,
bank_account,
country,
user,
business,
key
description
string
default:""

Optional free-text description.

Response

The list was created.

A blocklist, allowlist or custom list of one application.

uuid
string<uuid>
required

List identifier. Use it as list_uuid in the list and entry endpoints, and as the value of a workflow or transaction rule condition with value_type: "list".

name
string
required

List name, unique among the application's lists.

Maximum string length: 255
description
string
required

Free-text description. Empty string when not set.

list_type
enum<string>
required

blocklist: a match declines the session or transaction (system lists only, one per entry type). allowlist: matching items are trusted, for example a face allowlist skips the duplicated-face action; never overrides a blocklist match. custom: used in workflow and transaction rule conditions (value_type: "list").

Available options:
blocklist,
allowlist,
custom
entry_type
enum<string>
required

What the list holds: face, document (document number), phone, email, ip_address (IP address or CIDR range), device_fingerprint, wallet_address, bank_account, country (ISO 3166-1 alpha-3), user or business (your vendor_data), or key (any string). It decides how entry values are validated and matched.

Available options:
face,
document,
phone,
email,
ip_address,
device_fingerprint,
wallet_address,
bank_account,
country,
user,
business,
key
is_system
boolean
required

true for the lists Didit provisions: one blocklist per entry type (face, document, phone, email, ip_address, device_fingerprint, wallet_address, bank_account, user, business), the High Risk Countries custom list, and system allowlists. System lists cannot be renamed, edited or deleted; you can add and delete their entries.

entry_count
integer
required

Number of entries currently in the list.

Required range: x >= 0
last_entry_added_at
string<date-time> | null
required

When the newest current entry was added. null for an empty list.

created_at
string<date-time>
required

When the list was created.

updated_at
string<date-time>
required

When the list was last updated.