> ## 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. # Add to Blocklist > POST /v3/blocklist/add/: blocklist the face, document, phone number or email of a Didit verification session so matching new sessions are declined. Add to Blocklist API Prompt Copy prompt to clipboard \

\`Blocklist the face, document, phone number or email address of one of my Didit verification sessions through the Management API.

Endpoint:
POST https://verification.didit.me/v3/blocklist/add/

Authentication:
Use the x-api-key header with my Didit API key. A scoped API key needs workflows: write.

Goal:
\- After reviewing a fraudulent session, block what it collected so the same person is declined next time.

Request body (application/json):
\{
"session_id": "33333333-4444-5555-6666-777777777777", // required: a verification session of my application
"blocklist_face": true,       // optional, default false
"blocklist_document": true,   // optional, default false
"blocklist_phone": false,     // optional, default false
"blocklist_email": false      // optional, default false
}
At least one blocklist_* flag must be true.

Behavior:
\- Didit uses the session's most recent record of each selected type.
\- Each selected record is flagged as blocklisted and gets an entry, linked to the session, in the matching system blocklist (added_by "api").
\- From then on, new sessions with a matching face, document number, phone number or email address are declined.
\- The session itself and sessions that already finished are not changed.
\- Safe to repeat: an item already listed keeps its single entry, and its blocklisted_at is refreshed.
\- All or nothing: Didit checks every selected item first. If one is missing, nothing is blocklisted.
\- A document needs its issuing state, document type, document number and full name.

Example call:
curl -X POST "https://verification.didit.me/v3/blocklist/add/" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"session_id": "33333333-4444-5555-6666-777777777777", "blocklist_face": true, "blocklist_document": true}'

Example response (200):
\{ "message": "Successfully updated blocklist." }

Failure modes:
\- 400: session_id is missing ({ "session_id": ["This field is required."] }) or not a UUID ({ "session_id": ["Must be a valid UUID."] }); the session is not a verification session of this application ({ "non_field_errors": ["Session not found"] }; business verification sessions are not accepted); no flag is true ({ "non_field_errors": ["Must specify at least one item to blocklist"] }); the session has no record of a selected type ({ "non_field_errors": ["Session does not have a face record"] }); or the document lacks a required field.
\- 401: the API key has expired.
\- 403: missing or invalid x-api-key ({ "detail": "You do not have permission to perform this action." }), or a scoped key without workflows: write.
\- 429: rate limited (see /integration/rate-limiting); back off and retry.

Side effects:
\- Writes entries to the system face, document, phone and email blocklists and blocks matching new sessions.

To block a value without a session, or an IP address, device fingerprint, user or business, use POST /v3/lists/{list_uuid}/entries/ on the matching system blocklist instead.

For the full integration shape, see /integration/integration-prompt.`

\
Paste into Blocklist what one verification session collected: its face, identity document, phone number or email address. Didit flags each selected record as blocklisted and adds it to the matching system blocklist, linked to the session. New sessions with a matching face, document number, phone number or email address are declined from then on.> [!NOTE] > > The call is all-or-nothing: if the session has no record of a selected type, or the document lacks its issuing state, document type, document number or full name, it returns `400` and nothing is blocklisted. Repeating the call for an item that is already blocklisted is safe.To check what is blocked, use [List blocklisted items](/management-api/blocklist/list.md). To lift a block, use [Remove from blocklist](/management-api/blocklist/remove.md). To block an IP address, device fingerprint, user, business or a value without a session, add an entry to the matching system blocklist with [Create entry](/management-api/lists/create-entry.md). See [User blocklist](/entities/users/blocklist.md) for how blocklists are enforced. ## OpenAPI ````yaml POST /v3/blocklist/add/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: Identity verification API. Authenticate with x-api-key header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/blocklist/add/: post: tags: - Blocklist summary: Add session items to the blocklist description: >- Blocklists the face, identity document, phone number or email address of one person verification session of the application. For each selected type, Didit takes the session's most recent record, flags it as blocklisted and adds an entry linked to the session to the matching system blocklist (`added_by: "api"`), so new sessions with a matching face, document number, phone number or email address are declined. Every selected item is checked first, so if one is missing nothing is blocklisted; repeating the call for an item already listed keeps its single entry and refreshes `blocklisted_at`. The session itself and sessions that already finished are not changed. A scoped API key needs `workflows: write`. operationId: add_to_blocklist requestBody: required: true content: application/json: schema: type: object required: - session_id description: At least one `blocklist_*` flag must be `true`. properties: session_id: type: string format: uuid description: >- A person verification session of your application. Deleted sessions are refused. blocklist_face: type: boolean default: false description: Blocklist the session's face. blocklist_document: type: boolean default: false description: >- Blocklist the session's identity document. The document needs its issuing state, document type, document number and full name. blocklist_phone: type: boolean default: false description: Blocklist the session's phone number. blocklist_email: type: boolean default: false description: Blocklist the session's email address. examples: Face and document: value: session_id: 33333333-4444-5555-6666-777777777777 blocklist_face: true blocklist_document: true Phone only: value: session_id: 33333333-4444-5555-6666-777777777777 blocklist_phone: true responses: '200': description: The selected items were blocklisted. content: application/json: schema: type: object required: - message properties: message: type: string description: Always `Successfully updated blocklist.` examples: Blocklisted: value: message: Successfully updated blocklist. '400': description: >- The body is invalid, the session is not a verification session of this application, or it has no record of a selected type. Nothing was blocklisted. content: application/json: examples: Unknown session: value: non_field_errors: - Session not found No item selected: value: non_field_errors: - Must specify at least one item to blocklist No face record: value: non_field_errors: - Session does not have a face record Incomplete document: value: non_field_errors: - >- To blocklist a document, the document must have an issuing state, document type, document number and full name Invalid session id: value: session_id: - Must be a valid UUID. Missing session id: value: session_id: - This field is required. '401': description: >- The scoped API key has expired. Other authentication failures return `403`. content: application/json: examples: Expired API key: value: detail: This API key has expired. '403': description: >- The `x-api-key` header is missing or invalid, or a scoped API key lacks `workflows: write` or is used from an IP address outside its allowlist. content: application/json: examples: Missing or invalid API key: value: detail: You do not have permission to perform this action. Scoped key without workflows access: value: detail: This API key has no write access to workflows. '429': $ref: '#/components/responses/RateLimitedWrite' security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST 'https://verification.didit.me/v3/blocklist/add/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "session_id": "33333333-4444-5555-6666-777777777777", "blocklist_face": true, "blocklist_document": true }' - lang: python label: Python source: |- import os import requests resp = requests.post( 'https://verification.didit.me/v3/blocklist/add/', headers={'x-api-key': os.environ['DIDIT_API_KEY']}, json={ 'session_id': '33333333-4444-5555-6666-777777777777', 'blocklist_face': True, 'blocklist_document': True, }, timeout=10, ) resp.raise_for_status() print(resp.json()['message']) - lang: javascript label: JavaScript source: >- const resp = await fetch('https://verification.didit.me/v3/blocklist/add/', { method: 'POST', headers: { 'x-api-key': process.env.DIDIT_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ session_id: '33333333-4444-5555-6666-777777777777', blocklist_face: true, blocklist_document: true, }), }); if (!resp.ok) throw new Error(`Blocklist failed: ${resp.status} ${await resp.text()}`); console.log((await resp.json()).message); components: responses: RateLimitedWrite: description: >- The shared write limit of 300 requests per minute per API key was exceeded. Honor `Retry-After` before retrying. content: application/json: schema: type: object required: - detail properties: detail: type: string example: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.