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

# Create List Entry

> Add an entry — face, document, IP, wallet, email, phone — to a Didit blocklist, allowlist, or custom list. Programmatic compliance and fraud controls.

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="Create List Entry API Prompt"
  prompt={`Add an entry to a Didit list (blocklist, allowlist, or custom) through the Management API.

Endpoint:
POST https://verification.didit.me/v3/lists/{list_uuid}/entries/

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

Goal:
- Insert a single entry into a list. Three add modes are supported:
1. By manual value — pass value matching the list's entry_type.
2. From a verification session — pass reference_session_id and Didit auto-extracts the right value based on entry_type (face, document, phone, email, ip_address, device_fingerprint) and marks the underlying model as blocklisted.
3. From a transaction / vendor user / vendor business — pass reference_object_uuid and metadata.reference_type so the console links the entry back to the source.

Path parameter:
- list_uuid — list UUID from GET /v3/lists/. For face entries, prefer POST /v3/lists/{list_uuid}/entries/face-upload/ unless you also have a reference_session_id.

Request body (application/json):
{
"value": "string",                  // required unless reference_session_id is provided; used to disambiguate when both are sent
"reference_session_id": "uuid",     // optional — auto-extracts the value and links back to the session
"reference_object_uuid": "uuid",    // optional — UUID of the source entity (transaction / vendor_user / vendor_business)
"display_label": "string",          // optional
"comment": "string",                // optional, reason / note
"metadata": {                       // optional
"reference_type": "transaction" | "vendor_user" | "vendor_business",
"reference_id": "uuid",
// For document entries: full_name, issuing_state, document_type
}
}

Value validation by entry_type:
- 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 accepted and converted).
- face, document, wallet_address, bank_account, user, business, key — any non-empty string.
All values are case-insensitive and normalized on storage (lowercased for most, uppercased for country codes).

Adding from a session — what Didit does:
- Looks up the session (must belong to the same application).
- Extracts the value based on entry_type:
- face — links biometric for future matching, sets is_blocklisted on the Face model.
- document — extracts document number, stores full_name / issuing_state / document_type in metadata, sets is_blocklisted on the KYC model.
- phone / email — sets is_blocklisted on the Phone / Email model.
- ip_address / device_fingerprint — extracts from session location data.
- Sets reference_session and reference_object_uuid on the entry. If the session has multiple instances of the same type (e.g. two phone numbers), also pass value to disambiguate.

Example calls:
# Manual value
curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/" \\
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \\
-d '{"value": "+14155552671", "comment": "Reported fraud"}'

# From a session
curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/" \\
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \\
-d '{"reference_session_id": "a1b2c3d4-..."}'

# From a transaction
curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/" \\
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \\
-d '{"value": "0xABC...", "reference_object_uuid": "txn-uuid", "metadata": {"reference_type": "transaction"}}'

Failure modes:
- 400 — value fails the entry_type validator, list is a face-type without reference_session_id (use face-upload), reference_session_id has no data of the requested type, or the session doesn't belong to this application.
- 401 — missing or malformed x-api-key.
- 403 — canonical { "detail": "You do not have permission to perform this action." } envelope.
- 404 — list not found.

Side effects:
- For system blocklists, the underlying entity is immediately marked is_blocklisted and will be declined in future verifications/screenings.

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

Add an entry to a list. The value is validated based on the list's entry type:

* **email**: Must be a valid email address
* **phone**: Must be a valid international phone number (auto-normalized to E.164)
* **ip\_address**: Must be a valid IP address or CIDR range (e.g. `192.168.1.1` or `10.0.0.0/8`)
* **device\_fingerprint**: Must be at least 8 alphanumeric characters
* **country**: Must be a valid [ISO 3166-1 alpha-3 country code](/core-technology/id-verification/supported-documents-id-verification) (e.g. `USA`, `GBR`, `ESP`). Alpha-2 codes (e.g. `US`) are accepted and automatically converted to alpha-3.
* **face**, **document**, **wallet\_address**, **bank\_account**, **user**, **business**, **key**: Any non-empty string

<Info>
  All entry values are **case-insensitive**. Values are normalized on storage (lowercased for most types, uppercased for country codes) and matched case-insensitively during verification. For example, blocking `User@Example.COM` will also catch `user@example.com`.
</Info>

For face entries, use the [Upload face](/management-api/lists/upload-face) endpoint instead — unless you provide a `reference_session_id`, which handles face blocklisting automatically (including biometric matching).

## Request body

| Field                   | Type          | Required    | Description                                                                                                                                                                                                                                   |
| ----------------------- | ------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`                 | string        | Conditional | The value to add (phone number, email, IP, etc.). Required unless `reference_session_id` is provided. When both `value` and `reference_session_id` are provided, the value is used to disambiguate (e.g. when a session has multiple phones). |
| `reference_session_id`  | string (UUID) | No          | Verification session ID. Didit auto-extracts the value from the session based on the list's entry type, links the entry back, and marks the underlying model as blocklisted. See [Adding from a session](#adding-from-a-session).             |
| `reference_object_uuid` | string (UUID) | No          | UUID of the source entity (transaction UUID, vendor user `didit_internal_id`, etc.). Stored on the entry for traceability — lets you navigate from the blocklist back to the original entity.                                                 |
| `display_label`         | string        | No          | Human-readable label shown in the console                                                                                                                                                                                                     |
| `comment`               | string        | No          | Comment or reason for adding                                                                                                                                                                                                                  |
| `metadata`              | object        | No          | Additional structured data. Commonly used for document context (`full_name`, `issuing_state`, `document_type`) or entity references (`reference_type`, `reference_id`).                                                                       |

## Adding from a session

When you provide a `reference_session_id`, Didit automatically:

1. Looks up the session (must belong to the same application)
2. Extracts the value based on the list's entry type:
   * **face** → links the biometric data for future matching, sets `is_blocklisted` on the Face model
   * **document** → extracts document number, stores full name / issuing state / document type in metadata, sets `is_blocklisted` on the KYC model
   * **phone** → extracts the phone number, sets `is_blocklisted` on the Phone model
   * **email** → extracts the email address, sets `is_blocklisted` on the Email model
   * **ip\_address** → extracts the IP from the session's location data
   * **device\_fingerprint** → extracts the device fingerprint from the session's location data
3. Sets `reference_session` and `reference_object_uuid` on the entry for traceability

Returns `400` if the session is not found or does not contain data for the requested entry type.

### Disambiguating multiple values

If a session has multiple instances of the same type (e.g. two phone numbers from a multi-step workflow), pass both `reference_session_id` and `value`. The backend finds the matching instance and returns `400` if the value doesn't match any data in the session.

```json theme={null}
{
  "reference_session_id": "a1b2c3d4-...",
  "value": "+34612345678"
}
```

If you omit `value`, the most recently created instance is used.

## Referencing transactions, users, and businesses

When blocklisting data from a transaction or vendor user/business, pass the entity's UUID as `reference_object_uuid` and indicate the source type in `metadata`:

```json theme={null}
{
  "value": "0xABC123...",
  "reference_object_uuid": "txn-uuid-here",
  "metadata": {
    "reference_type": "transaction",
    "reference_id": "txn-uuid-here"
  }
}
```

This lets you navigate from the blocklist entry back to the original transaction, user, or business in the console.

| Source entity        | `reference_object_uuid`                         | `metadata.reference_type`               |
| -------------------- | ----------------------------------------------- | --------------------------------------- |
| Verification session | Auto-set by backend (face/KYC/phone/email UUID) | Not needed — use `reference_session_id` |
| Transaction          | Transaction UUID                                | `"transaction"`                         |
| Vendor user          | `didit_internal_id`                             | `"vendor_user"`                         |
| Vendor business      | `didit_internal_id`                             | `"vendor_business"`                     |

<RequestExample>
  ```bash Manual value theme={null}
  curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"value": "+14155552671", "comment": "Reported as fraud"}'
  ```

  ```bash From session theme={null}
  curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"reference_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'
  ```

  ```bash From session (disambiguate) theme={null}
  curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"reference_session_id": "a1b2c3d4-...", "value": "+34612345678"}'
  ```

  ```bash From transaction theme={null}
  curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "value": "0xd15ae8c92c304c5ca11778143480e391",
      "reference_object_uuid": "e7f8a9b0-1234-5678-abcd-ef0123456789",
      "metadata": {"reference_type": "transaction"}
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Manual value theme={null}
  {
    "uuid": "a1b2c3d4-...",
    "value": "+14155552671",
    "display_label": "",
    "comment": "Reported as fraud",
    "added_by": "api",
    "reference_session_id": null,
    "reference_session_number": null,
    "reference_object_uuid": null,
    "metadata": null,
    "created_at": "2025-06-09T12:26:54Z"
  }
  ```

  ```json From session (document) theme={null}
  {
    "uuid": "f9e8d7c6-...",
    "value": "AB1234567",
    "display_label": "John Doe - AB1234567",
    "comment": "",
    "added_by": "console",
    "reference_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "reference_session_number": 42,
    "reference_object_uuid": "b2c3d4e5-...",
    "metadata": {
      "full_name": "John Doe",
      "issuing_state": "USA",
      "document_type": "PASSPORT",
      "document_number": "SAMPLE-DOC-12345"
    },
    "created_at": "2025-06-09T12:30:00Z"
  }
  ```

  ```json From transaction theme={null}
  {
    "uuid": "11223344-...",
    "value": "0xd15ae8c92c304c5ca11778143480e391",
    "display_label": "",
    "comment": "",
    "added_by": "console",
    "reference_session_id": null,
    "reference_session_number": null,
    "reference_object_uuid": "e7f8a9b0-1234-5678-abcd-ef0123456789",
    "metadata": {
      "reference_type": "transaction"
    },
    "created_at": "2025-06-09T12:35:00Z"
  }
  ```
</ResponseExample>