Skip to main content
POST
curl
Add an entry to a list. The value is validated against the list’s entry type:
  • email: a valid email address
  • phone: a valid international phone number, stored in E.164 (for example +14155552671)
  • ip_address: a valid IP address or CIDR range (e.g. 192.168.1.1 or 10.0.0.0/8)
  • device_fingerprint: at least 8 characters among letters, digits, -, _, : and .. A blocklist refuses a fingerprint that several distinct devices have reported, because blocking it would decline unrelated people.
  • country: a valid ISO 3166-1 alpha-3 country code (e.g. USA, GBR, ESP). Alpha-2 codes (e.g. US) are accepted and automatically converted to alpha-3.
  • user, business: the vendor_data of the user or business
  • face, document, wallet_address, bank_account, key: any non-empty string
All entry values are case-insensitive. Values you send are normalized on storage (phone numbers to E.164, country codes to upper case, everything else to lower case) and matched case-insensitively during verification. For example, blocking User@Example.COM will also catch user@example.com. A list holds each value once: adding a value that is already in the list returns 400.
For a face, use Upload face when you only have an image, or send a reference_session_id to take the face of an existing session. A face entry needs a stored face to match against, which a typed value does not provide.

Adding from a session

When you provide a reference_session_id, Didit:
  1. Looks up the session (it must belong to the same application)
  2. Reads the value from the session’s most recent record of the list’s entry type:
    • face: the face of the liveness selfie; value is the face UUID
    • document: the document number; the full name, issuing state, document type, region and document number are stored in metadata, and display_label defaults to the holder’s name and document number
    • phone: the phone number
    • email: the email address
    • ip_address: the IP address of the session
    • device_fingerprint: a fingerprint that identifies one device, preferring a device that completed a verification step. On a blocklist, Didit refuses a session that only has a device-class fingerprint, or one completed on more than one device: send the exact fingerprint as value in that case.
  3. Links the entry to the session (reference_session_id) and to the record (reference_object_uuid) for traceability
On the system face, document, phone and email blocklists, the record is also flagged as blocklisted, so new sessions that match it are declined. For any other entry type, send value as well. Returns 400 if the session is not found or does not contain data for the requested entry type.

Faces from the document-capture selfie

While the user photographs their document, the front camera can take a selfie of them (the front_image_camera_front and back_image_camera_front images of the ID verification report). That face can be added to the face blocklist as well as the liveness face: pass face_image_source with the image you want.
  • The entry is created only in the system face blocklist, and value must be left empty: Didit takes the face from the session’s selfie.
  • The selfie must contain one clear face. If it does not, the request returns 400 and nothing is added.
  • Each selfie can be added once. The entry’s metadata.face_image_source and metadata.reference_node_id say which selfie it came from.
  • In a workflow with more than one ID verification step, reference_node_id picks the step whose selfie to use. By default Didit uses the most recent ID verification that has that selfie.
  • From then on, the face is checked like any other blocklisted face: against the liveness selfie of every new session, and against every new document-capture selfie (see FRONT_CAMERA_FACE_IN_BLOCKLIST).
  • Deleting the entry removes the face from the blocklist, and it stops matching new sessions.

Sessions with several records of the same type

A session can hold more than one record of a type, for example two phone numbers from a multi-step workflow. Didit always reads the most recent one. If you send value together with reference_session_id, the entry stores your value but is still linked to that most recent record, and on a system blocklist that record is the one flagged. To list a value from an earlier record, add it by value alone, without reference_session_id:

Referencing transactions, users, and businesses

When blocklisting data from a transaction or vendor user/business, pass the entity’s UUID as reference_object_uuid and indicate the source type in metadata:
This lets you navigate from the blocklist entry back to the original transaction, user, or business in the console. Didit stores your metadata keys, except reference_image_url and front_image_url, which only Didit sets. For an entry read from a session, Didit adds its own keys to yours, and its keys win. On the system User and Business blocklists, Didit also sets the matching users or businesses to BLOCKED: those whose vendor_data equals value, or whose didit_internal_id equals reference_object_uuid. See User blocklist and Business blocklist.

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.

Headers

Idempotency-Key
string

Optional retry-safety key you choose for one operation, up to 255 characters (a UUID works). A request repeated with the same key, endpoint, query and body is answered with the first response, same status and same body, and runs and bills nothing a second time. The same key with another endpoint, query or body returns 409 idempotency_key_reused, and while the first request is still running, 409 idempotency_key_in_progress with Retry-After. A failed request (any 4xx or 5xx) is not stored, so you can send it again with the same key. Keys belong to your application, whether you call with an API key or an access token. See Retries and idempotency.

Required string length: 1 - 255

Path Parameters

list_uuid
string<uuid>
required

UUID of the list to add to. For a face you only have as an image, use Upload a face to a list instead.

Body

application/json

Send value, reference_session_id, or both. Which fields apply depends on the list's entry_type.

value
string

The value to list, validated against the list's entry_type: email a valid email address; phone a valid international number, stored in E.164; ip_address an IP address or CIDR range (for example 10.0.0.0/8); device_fingerprint at least 8 characters among letters, digits, -, _, : and . (a blocklist refuses a fingerprint that several distinct devices have reported); country an ISO 3166-1 alpha-2 or alpha-3 code, stored as alpha-3; user and business the vendor_data; any other type a non-empty string. Stored in lower case except phone numbers and country codes, and a list holds each value once (case-insensitive). Required unless reference_session_id is sent; must be left empty with a document-capture face_image_source.

reference_session_id
string<uuid>

A person or business verification session of your application to take the value from. Didit reads the session's most recent record of the list's entry type (face, document, phone, email, ip_address or device_fingerprint), links the entry to the session and to that record, and fills display_label and metadata for documents. For a device_fingerprint blocklist, a session that only has a device-class fingerprint, or was completed on more than one device, is refused: send the exact fingerprint as value. For other entry types, or when the session has no such record, send value too; your value is then stored and the entry is still linked to the session.

reference_object_uuid
string<uuid>

UUID of the record the entry stands for when it does not come from a session: a transaction UUID, or the didit_internal_id of a user or business. Pair it with metadata.reference_type. Replaced by the session's record when reference_session_id provides one.

face_image_source
enum<string>
default:liveness

Face lists with reference_session_id: which of the session's images the face is taken from. liveness (default) is the liveness selfie. front_image_camera_front and back_image_camera_front are the selfies the front camera took while the user photographed the front or back of their document: accepted only on the system face blocklist, with reference_session_id and an empty value. Each selfie can be added once and must show one clear face.

Available options:
liveness,
front_image_camera_front,
back_image_camera_front
reference_node_id
string | null

With a document-capture face_image_source: the ID verification node whose selfie to use, for workflows with more than one. Defaults to the most recent ID verification that has that image. Refused with liveness.

Maximum string length: 100
display_label
string

Human-readable label. When empty, Didit derives one from the session where it can (for example the holder's name and document number).

Maximum string length: 512
comment
string

Free-text note, such as the reason for listing.

metadata
object

Free-form JSON stored with the entry and returned as stored. Use reference_type and reference_id so the console links back to the source. reference_image_url and front_image_url are set by Didit only and are dropped if you send them. For an entry read from a session, Didit's keys are merged with yours.

Response

The entry was created.

One value in a list.

uuid
string<uuid>
required

Entry identifier. Use it as entry_uuid in Delete a list entry.

value
string
required

The listed value: a phone number in E.164, an email address, a document number, an IP address or CIDR range, a device fingerprint, a wallet address, a bank account, an ISO 3166-1 alpha-3 country code, a vendor_data, any string on a key list, or the UUID of the stored face on a face list. Values you send are stored in lower case, except phone numbers and country codes. Matching is case-insensitive.

display_label
string | null
required

Human-readable label. Didit fills it for entries taken from a session (for example the holder's name and document number) when you send none.

Maximum string length: 512
comment
string
required

Free-text note. Empty string when not set.

added_by
string | null
required

Who added the entry: api (an API key), a console user's email address or console, system or migration (entries Didit created), or rule (a transaction or monitoring rule action).

reference_session_id
string<uuid> | null
required

Verification session the entry was taken from. null when the entry was added by value.

reference_session_number
integer | null
required

Application-scoped number of that session, as shown in the console.

reference_session_type
enum<string> | null
required

kyc for a person verification session, kyb for a business verification session, null when there is no session.

Available options:
kyc,
kyb,
null
reference_object_uuid
string<uuid> | null
required

The record the entry stands for: the face, document, phone or email record read from a session, the face created by Upload a face to a list, or the UUID you sent (for example a transaction UUID or a user's didit_internal_id).

metadata
object | null
required

Extra context. Holds the keys Didit sets (listed here) merged with any metadata you sent when creating the entry, returned as stored. null when there is none.

created_at
string<date-time>
required

When the entry was added.

Last modified on November 1, 2026