> ## 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.

# Lists

> Manage Didit blocklists, allowlists, and custom lists for KYC, fraud, and transaction screening. All-in-one identity infrastructure, pay-per-call.

export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
  const [copied, setCopied] = React.useState(false);
  const handleCopy = e => {
    e.stopPropagation();
    if (!prompt) return;
    navigator.clipboard.writeText(prompt.trim()).then(() => {
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    });
  };
  const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
  return <div className="didit-agent-card">
      {}
      <div className="didit-agent-titlebar">
        <div className="didit-agent-dots" aria-hidden="true">
          <span className="didit-agent-dot didit-agent-dot-red"></span>
          <span className="didit-agent-dot didit-agent-dot-yellow"></span>
          <span className="didit-agent-dot didit-agent-dot-green"></span>
        </div>
        <span className="didit-agent-filename">{title}</span>
        <button type="button" className={`didit-agent-copy ${copied ? "didit-agent-copy-copied" : ""}`} onClick={handleCopy} title="Copy prompt to clipboard" aria-label={copied ? "Copied!" : "Copy prompt to clipboard"}>
          {copied ? <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <path d="M3 8.5l3.5 3.5L13 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
              </svg>
              <span>Copied</span>
            </> : <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <rect x="5" y="5" width="9" height="9" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
                <path d="M11 5V3.5A1.5 1.5 0 0 0 9.5 2h-6A1.5 1.5 0 0 0 2 3.5v6A1.5 1.5 0 0 0 3.5 11H5" stroke="currentColor" strokeWidth="1.5" />
              </svg>
              <span>Copy</span>
            </>}
        </button>
      </div>

      {}
      <pre className="didit-agent-body"><code>{prompt.trim()}</code></pre>

      {}
      <div className="didit-agent-footer">
        <span className="didit-agent-footer-label">Paste into</span>
        <div className="didit-agent-chips">
          {agents.map(name => <span key={name} className="didit-agent-chip">{name}</span>)}
        </div>
      </div>
    </div>;
};

<AgentPromptAccordion
  title="Lists API Prompt"
  prompt={`Manage Didit blocklists, allowlists, and custom lists through the Management API.

Base path:
https://verification.didit.me/v3/lists/

Authentication:
Use the x-api-key header with my Didit API key on every call.

Concepts:
- Blocklist — system-created, one per entry type. Items in a blocklist cause automatic decline during verification or transaction screening. Cannot be deleted or renamed.
- Allowlist — user-created. Used in workflow conditions and to suppress duplicate/reuse actions for trusted matching items.
- Custom — user-created. Flexible lists for workflow branching, monitoring rules, or manual review.

Supported entry_type values:
face, document, phone, email, ip_address, device_fingerprint, wallet_address, bank_account, user, business, country, key.

Endpoints I should know:
- GET /v3/lists/ — list all lists (filter by list_type, entry_type).
- POST /v3/lists/ — create allowlist or custom list (cannot create blocklists).
- GET /v3/lists/{list_uuid}/ — get one list.
- PATCH /v3/lists/{list_uuid}/ — rename or update description (system lists immutable).
- DELETE /v3/lists/{list_uuid}/ — delete allowlist/custom only. Returns 204.
- GET /v3/lists/{list_uuid}/entries/ — paginated entries; supports search query.
- POST /v3/lists/{list_uuid}/entries/ — add an entry by value, by reference_session_id, or by reference_object_uuid + metadata.reference_type ("transaction" | "vendor_user" | "vendor_business").
- POST /v3/lists/{list_uuid}/entries/face-upload/ — upload a base64 face image to a face-type blocklist; Didit extracts the biometric.
- DELETE /v3/lists/{list_uuid}/entries/{entry_uuid}/ — remove an entry. For system blocklists this auto-unblocks the underlying entity.

Value validation (Create entry):
- email — valid email address.
- phone — valid international phone number (auto-normalized to E.164).
- ip_address — IP or CIDR range (e.g. 10.0.0.0/8).
- device_fingerprint — at least 8 alphanumeric characters.
- country — ISO 3166-1 alpha-3 (alpha-2 is accepted and converted).
- Other types — any non-empty string. Values are case-insensitive and normalized on storage.

Traceability:
- Pass reference_session_id when blocklisting from a verification session — Didit auto-extracts the right value (face/document/phone/email/IP/device), marks the underlying model as blocklisted, and links the entry back to the session. If the session has multiple instances of the same type, also pass value to disambiguate.
- Pass reference_object_uuid plus metadata.reference_type ("transaction" | "vendor_user" | "vendor_business") when blocklisting from a transaction or vendor user/business so the console can link back to the source.

Common failure modes:
- 400 — value fails the entry_type validator, list_type is wrong for the operation (e.g. POST face-upload on a non-face list), or reference_session_id has no data of the requested type.
- 401 — missing or malformed x-api-key.
- 403 — canonical { "detail": "You do not have permission to perform this action." } envelope when the list belongs to a different application or the action is not allowed (e.g. delete a system blocklist).
- 404 — list or entry not found in this application.
- 409 — list name already exists in this application (on create or rename).

Side effects:
- Adding to a system blocklist immediately blocks future matches at verification/screening time.
- Deleting an entry from a system blocklist unblocks the matching entity.
- Lists are referenced by workflow status_rules (value_type: "list") for runtime list checks.

For the full integration shape (auth, retries, error handling), see /integration/integration-prompt.`}
/>

The Lists API lets you manage typed lists for your application. System blocklists are automatically created and checked during verification and transaction screening. You can also create allowlists and custom lists for workflow conditions.

## Concepts

| Type          | Description                                                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Blocklist** | System-created, one per entry type. Items in a blocklist cause automatic decline during verification or transaction screening. |
| **Allowlist** | User-created. Used in workflow conditions and to suppress duplicate/reuse actions for trusted matching items.                  |
| **Custom**    | User-created. Flexible lists for workflow branching, monitoring rules, or manual review.                                       |

## Entry types

| Entry type           | Checked during                              | On match             |
| -------------------- | ------------------------------------------- | -------------------- |
| `face`               | Liveness verification                       | Session declined     |
| `document`           | ID verification (OCR)                       | Session declined     |
| `phone`              | Phone verification                          | Session declined     |
| `email`              | Email verification                          | Session declined     |
| `ip_address`         | Device & IP Analysis (supports CIDR ranges) | Session declined     |
| `device_fingerprint` | Device & IP Analysis                        | Session declined     |
| `wallet_address`     | Transaction screening                       | Transaction declined |
| `bank_account`       | Transaction screening                       | Transaction declined |
| `user`               | Transaction screening                       | User blocked         |
| `business`           | Transaction screening                       | Business blocked     |
| `country`            | Workflow conditions                         | Configurable         |
| `key`                | Custom use                                  | Configurable         |

## Allowlists

Allowlists do not override blocklists or authenticity checks. They only suppress duplicate/reuse actions for the same entry type. For example, a face in a face allowlist can skip the `DUPLICATED_FACE` action, an IP in an IP allowlist can skip the `DUPLICATED_IP_ADDRESS` action, and a device fingerprint in a device allowlist can skip the `DUPLICATED_DEVICE_FINGERPRINT` action. Didit still records an informational allowlist warning so you can audit why the duplicate action did not run.

## System blocklists

Every application automatically gets 10 system blocklists (one per supported entry type). These cannot be deleted or renamed. You can add entries to them via the API or from the console.

## Traceability

Every blocklist entry can be linked back to its source entity so you can navigate from the list to the original record:

* **From a session** — pass `reference_session_id` when [creating an entry](/management-api/lists/create-entry). Didit auto-extracts the value (face, document, phone, email, IP, or device), marks the underlying model as blocklisted, and links the entry back to the session. If the session has multiple instances of the same type, also pass `value` to disambiguate.
* **From a transaction, user, or business** — pass `reference_object_uuid` with the entity's UUID and include `metadata.reference_type` (`"transaction"`, `"vendor_user"`, or `"vendor_business"`) so the console can link back to the original record.

## Endpoints

<CardGroup cols={2}>
  <Card title="List all lists" icon="list" href="/management-api/lists/list">
    Retrieve all lists for an application.
  </Card>

  <Card title="List entries" icon="table" href="/management-api/lists/list-entries">
    Retrieve entries in a list.
  </Card>

  <Card title="Create entry" icon="circle-plus" href="/management-api/lists/create-entry">
    Add a value to a blocklist — by value, session reference, or transaction reference.
  </Card>

  <Card title="Delete entry" icon="circle-minus" href="/management-api/lists/delete-entry">
    Remove an entry and unblock the underlying entity.
  </Card>

  <Card title="Upload face" icon="face-smile" href="/management-api/lists/upload-face">
    Upload a face image directly to a face blocklist.
  </Card>
</CardGroup>