> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# User Blocklist
> How Didit enforces blocks on User entities — identifier types (face, document, email, phone, vendor_data), automatic blocklisting, manual blocklisting.
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
| Type | Key | Matches when… |
| ------------------ | -------------------- | ------------------------------------------------------------------------------------------- |
| Face | `FACE` | A new session's liveness selfie matches the blocklisted face |
| Document number | `DOCUMENT` | A new ID submission matches the blocklisted document number |
| Email | `EMAIL` | A new session or transaction uses the blocklisted email |
| Phone | `PHONE` | A new session or transaction uses the blocklisted phone |
| IP address | `IP_ADDRESS` | The submitter's IP matches — supports single IPs (`1.2.3.4`) and CIDR ranges (`10.0.0.0/8`) |
| Device fingerprint | `DEVICE_FINGERPRINT` | The submitter's device fingerprint matches |
| User | `USER` | The 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 Device & IP Analysis in a session.
* User vendor\_data: enforced during session or transaction creation.
## How blocklisting happens
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`.
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.
An analyst blocklists a user from *Users → \[user] → Actions → Add to blocklist*, choosing one or more identifiers to capture.
Use the [Lists API](/management-api/lists/overview) 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.
| List | Created by | Description |
| ------------------------- | ---------- | --------------------------------------------------------- |
| System Face Blocklist | Didit | Canonical face blocklist for the application |
| System Document Blocklist | Didit | Canonical document number blocklist |
| System Email Blocklist | Didit | Canonical email blocklist |
| System Phone Blocklist | Didit | Canonical phone blocklist |
| System User Blocklist | Didit | Blocked `vendor_data` identifiers |
| Custom blocklists | You | Scoped lists, e.g. per region, per partner, per risk tier |
## Adding a user to the blocklist via API
Use the [Lists API](/management-api/lists/overview) 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](/management-api/lists/list) filtered by `entry_type=user` and `is_system=true` to find the system User blocklist.
2. [Create an entry](/management-api/lists/create-entry) on that list with `value` set to the user's `vendor_data`.
To block a user by face, see [Faces & biometrics](/entities/users/faces-and-biometrics#uploading-a-face-to-the-blocklist). To block by email, phone, document, or IP, use the corresponding system blocklist with the appropriate identifier in `value`.
## Enforcement flow
```mermaid theme={null}
sequenceDiagram
participant Client
participant Didit
participant Lists as Blocklist check
participant Workflow
Client->>Didit: POST /v3/session/ (vendor_data=user-42)
Didit->>Lists: Does user-42 match a USER blocklist?
Lists-->>Didit: Match found
Didit-->>Client: Session auto-declined (reason: blocked_user)
```
For face and document blocklists, the check happens at the verification step:
```mermaid theme={null}
sequenceDiagram
participant User
participant Didit
participant Lists as Face Blocklist
User->>Didit: Liveness capture
Didit->>Lists: Embedding search
Lists-->>Didit: Match similarity > threshold
Didit-->>User: Session declined (reason: blocked_face)
```
## Removing from the blocklist
* **Console**: *Blocklist → \[type] → row actions → Remove*.
* **API**: use the [Delete entry](/management-api/lists/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](/console/audit-logs):
* 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
Full blocklist / allowlist API reference.
Manage blocklists from the UI.
How face blocklists work.