Skip to main content
Blocklists prevent users who have failed your compliance checks from creating new sessions or running new transactions. Didit supports blocklists by identifier type, so you can block the same bad actor across multiple data points (face, document, email, phone, user vendor_data).

​
Supported identifier types for Users

TypeKeyMatches when…
FaceFACEA new session’s liveness selfie matches the blocklisted face
Document numberDOCUMENTA new ID submission matches the blocklisted document number
EmailEMAILA new session or transaction uses the blocklisted email
PhonePHONEA new session or transaction uses the blocklisted phone
IP addressIP_ADDRESSThe submitter’s IP matches — supports single IPs (1.2.3.4) and CIDR ranges (10.0.0.0/8)
Device fingerprintDEVICE_FINGERPRINTThe submitter’s device fingerprint matches
UserUSERThe session or transaction uses the blocklisted vendor_data
Each identifier type is enforced at the natural touchpoint:
  • Face and document: enforced during a new session.
  • Email and phone: enforced during a session step that collects them, or during a transaction payload.
  • IP and device: enforced during IP analysis in a session.
  • User vendor_data: enforced during session or transaction creation.

​
How blocklisting happens

1

Automatic — on a declined session

When a session is declined and your workflow’s auto-blocklist setting is enabled, Didit automatically adds relevant identifiers (face, document, email, phone) to the corresponding system blocklists and transitions the user to BLOCKED.
2

Automatic — on blocklist match

When an incoming session matches an existing blocklist entry, the session is auto-declined with a reason code like blocked_face, blocked_document, blocked_email, etc.
3

Manual — from the console

An analyst blocklists a user from Users → [user] → Actions → Add to blocklist, choosing one or more identifiers to capture.
4

Programmatic — via the Lists API

Use the Lists API to add entries programmatically. This is the same API the console uses under the hood.

​
System lists vs custom lists

Every application has system blocklists — one per identifier type — that Didit auto-manages. You cannot rename or delete them. Custom lists are yours to create, name, and scope.
ListCreated byDescription
System Face BlocklistDiditCanonical face blocklist for the application
System Document BlocklistDiditCanonical document number blocklist
System Email BlocklistDiditCanonical email blocklist
System Phone BlocklistDiditCanonical phone blocklist
System User BlocklistDiditBlocked vendor_data identifiers
Custom blocklistsYouScoped lists, e.g. per region, per partner, per risk tier

​
Adding a user to the blocklist via API

Use the Lists API to add a blocklist entry. To block a user by vendor_data, add a USER-type entry to the corresponding blocklist:
  1. List all lists filtered by entry_type=user and is_system=true to find the system User blocklist.
  2. Create an entry on that list with value set to the user’s vendor_data.
To block a user by face, see Faces & biometrics. To block by email, phone, document, or IP, use the corresponding system blocklist with the appropriate identifier in value.

​
Enforcement flow

For face and document blocklists, the check happens at the verification step:

​
Removing from the blocklist

  • Console: Blocklist → [type] → row actions → Remove.
  • API: use the Delete entry endpoint with the list UUID and entry UUID.
Removing the entry does not automatically move the user back to ACTIVE — use PATCH /v3/users/{vendor_data}/update-status/ to change status if you want to allow new sessions.

​
Blocklist audit trail

Every add/remove on a blocklist is logged to the audit log:
  • Who added the entry (user email or 'system', 'api').
  • When.
  • Optional comment explaining the reason.
  • Linked session or transaction if the entry was generated automatically.

​
Next steps

Lists API

Full blocklist / allowlist API reference.

Console blocklist

Manage blocklists from the UI.

Faces & biometrics

How face blocklists work.