> ## 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. # List Blocklisted Items > GET /v3/blocklist/: list the faces, documents, phone numbers and emails from your Didit sessions that are blocklisted, newest first, in one feed. List Blocklisted Items API Prompt Copy prompt to clipboard \

\`List the blocklisted faces, documents, phone numbers and email addresses of my Didit verification sessions through the Management API.

Endpoint:
GET https://verification.didit.me/v3/blocklist/

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

Goal:
\- Get one paginated feed of every session record that is currently blocklisted, to build a "Blocked" screen or audit what my team has blocked.

Behavior:
\- Items are sorted by blocklisted_at, newest first. Items of deleted sessions are not included.
\- Each item has a type ("face", "document", "phone" or "email") and the session it belongs to (session_id, session_number). Fields that do not apply to the type are null.
\- The feed covers records blocklisted from a session: with POST /v3/blocklist/add/, from the console, or with a list entry created from reference_session_id. It does not include values added to a list by hand, uploaded faces, faces taken from a document-capture selfie, or IP address, device fingerprint, wallet, bank account, user and business entries. Read those with GET /v3/lists/{list_uuid}/entries/ on the matching system blocklist.
\- face_image and front_image are short-lived signed URLs, issued again on every call; a scoped key without media: read gets null instead.

Query parameters (all optional):
\- item_type: "face" | "document" | "phone" | "email". When omitted, every type is returned.
\- limit: page size (default 50, at most 1000000).
\- offset: pagination offset (default 0).

Example call:
curl -X GET "https://verification.didit.me/v3/blocklist/?item_type=document" \
-H "x-api-key: YOUR_API_KEY"

What to read from the response:
\- count / next / previous: standard pagination envelope.
\- results[].type, session_id, session_number, blocklisted_at.
\- face items: face_image.
\- document items: document_type (for example "P" passport, "ID" national ID, "DL" driver's license), document_number, front_image.
\- phone items: phone_number (E.164), country_code (ISO 3166-1 alpha-2).
\- email items: email.

Failure modes:
\- 400: an unknown item_type, or limit/offset above 1000000.
\- 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: read.
\- 429: rate limited (see /integration/rate-limiting); back off and retry.

Side effects: none. This is a pure read.

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

\
Paste into List the faces, identity documents, phone numbers and email addresses of your verification sessions that are currently blocklisted, newest first. Each item points to the session it came from, so you can open it in the console or fetch its decision.This feed shows what was blocklisted **from a session**: with [Add to blocklist](/management-api/blocklist/add.md), from the console, or with a [list entry](/management-api/lists/create-entry.md) created from `reference_session_id`. Values typed into a list, [uploaded faces](/management-api/lists/upload-face.md), faces taken from a document-capture selfie and the other entry types (IP address, device fingerprint, wallet, bank account, user, business) live only in the system blocklists: read them with [List entries](/management-api/lists/list-entries.md).See [Blocklist users](/console/blocklist-users.md) for how blocklisting works in the console. ## OpenAPI ````yaml GET /v3/blocklist/ 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/: get: tags: - Blocklist summary: List blocklisted items description: >- Returns one paginated feed of the faces, identity documents, phone numbers and email addresses of the application's verification sessions that are currently blocklisted, newest `blocklisted_at` first; filter with `item_type`. Items of deleted sessions are not included. The feed covers records blocklisted from a session (with [Add session items to the blocklist](https://docs.didit.me/management-api/blocklist/add), from the console, or by a list entry created from a session); values added to a list by hand, uploaded faces, faces from a document-capture selfie and the other entry types are read with [List list entries](https://docs.didit.me/management-api/lists/list-entries). `face_image` and `front_image` are short-lived signed URLs, and a scoped API key without `media: read` receives `null`. A scoped API key needs `workflows: read`. operationId: list_blocklist_items parameters: - name: item_type in: query required: false description: Only items of this type. When omitted, every type is returned. schema: type: string enum: - face - document - phone - email - name: limit in: query required: false description: >- Page size. Defaults to 50. A value above 1000000 returns `400`; zero, a negative or a non-numeric value falls back to 50. schema: type: integer default: 50 minimum: 1 maximum: 1000000 - name: offset in: query required: false description: >- Zero-based index of the first item to return. Prefer following `next`. A value above 1000000 returns `400`; a negative or non-numeric value falls back to 0. schema: type: integer maximum: 1000000 minimum: 0 default: 0 responses: '200': description: A page of blocklisted items, newest first. content: application/json: schema: type: object required: - count - next - previous - results properties: count: type: integer minimum: 0 description: Total number of blocklisted items matching the filters. next: type: string format: uri nullable: true description: Absolute URL of the next page, or `null` on the last page. previous: type: string format: uri nullable: true description: >- Absolute URL of the previous page, or `null` on the first page. results: type: array items: $ref: '#/components/schemas/BlocklistedItem' examples: Mixed feed: value: count: 2 next: null previous: null results: - type: document session_id: 33333333-4444-5555-6666-777777777777 session_number: 1042 blocklisted_at: '2026-10-12T10:06:12.701553Z' face_image: null document_type: ID document_number: X1234567 front_image: >- https://media.example.com/documents/front.jpg?expires=1760263938&signature=8b2e47 phone_number: null country_code: null email: null - type: phone session_id: 77777777-8888-9999-0000-111111111111 session_number: 1017 blocklisted_at: '2026-10-08T15:31:09.400127Z' face_image: null document_type: null document_number: null front_image: null phone_number: '+14155552671' country_code: US email: null '400': description: A query parameter is invalid. content: application/json: examples: Unknown item type: value: item_type: - '"wallet" is not a valid choice.' Limit too large: value: - limit must not exceed 1000000. '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: read` 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 read access to workflows. '429': description: >- The shared read limit of 600 requests per minute per API key was exceeded. Honor `Retry-After` before retrying. content: application/json: examples: Rate limited: value: detail: >- GET request rate limit exceeded. You can make up to 600 requests per minute. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X GET 'https://verification.didit.me/v3/blocklist/?item_type=document' \ -H 'x-api-key: YOUR_API_KEY' - lang: python label: Python source: |- import os import requests resp = requests.get( 'https://verification.didit.me/v3/blocklist/', headers={'x-api-key': os.environ['DIDIT_API_KEY']}, params={'item_type': 'document'}, timeout=10, ) resp.raise_for_status() for item in resp.json()['results']: print(item['session_id'], item['document_type'], item['document_number']) - lang: javascript label: JavaScript source: >- const resp = await fetch('https://verification.didit.me/v3/blocklist/?item_type=document', { headers: { 'x-api-key': process.env.DIDIT_API_KEY }, }); if (!resp.ok) throw new Error(`Request failed: ${resp.status}`); const page = await resp.json(); console.log(page.count, page.results); components: schemas: BlocklistedItem: type: object description: >- One blocklisted face, identity document, phone number or email address of a verification session. Fields that do not apply to the item's `type` are `null`. required: - type - session_id - session_number - blocklisted_at - face_image - document_type - document_number - front_image - phone_number - country_code - email properties: type: type: string enum: - face - document - phone - email description: What was blocklisted. session_id: type: string format: uuid description: Verification session the item belongs to. session_number: type: integer nullable: true description: Application-scoped number of that session, as shown in the console. blocklisted_at: type: string format: date-time description: When the item was last blocklisted. face_image: type: string nullable: true description: >- Face items: short-lived signed URL, issued again on every call; `null` for a scoped API key without `media: read`. Also `null` when no reference image is stored. document_type: type: string nullable: true description: >- Document items: document type code, for example `P` (passport), `ID` (national ID), `DL` (driver's license) or `RP` (residence permit). document_number: type: string nullable: true description: >- Document items: the document number, or the personal number when the document has none. front_image: type: string nullable: true description: >- Document items: front image of the document, short-lived signed URL, issued again on every call; `null` for a scoped API key without `media: read`. phone_number: type: string nullable: true description: 'Phone items: the phone number in E.164.' country_code: type: string nullable: true description: 'Phone items: ISO 3166-1 alpha-2 country of the number.' email: type: string nullable: true description: 'Email items: the email address.' 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.