Skip to main content
POST
curl
Upload a base64-encoded face image to a face blocklist or allowlist. Didit detects the faces in the image, keeps the largest one, stores the image and a crop of that face, and computes the biometric face template that new sessions are compared against. The new entry’s value is the UUID of that face. Only available for lists with entry_type: face and list_type: blocklist or list_type: allowlist.
If you’re blocklisting or allowlisting a face from an existing session, use Create entry with reference_session_id instead: the entry links back to the session.
The image must contain a clearly visible face and be at most 2 MB once decoded. If no face is detected, the request returns 400 and no entry is created. If face analysis is temporarily unavailable, it returns 503: retry later.
To remove the face from the list, delete its entry: it stops matching new sessions.

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 a list with entry_type: face and list_type: blocklist or allowlist.

Body

application/json
image
string<byte>
required

Base64-encoded JPEG or PNG, at most 2 MB once decoded, showing a clearly visible face. Send the bare base64 string, without a data:image/...;base64, prefix.

comment
string
default:""

Optional free-text note, such as the reason for listing.

Response

The face 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 11, 2026