Skip to main content
POST
/
v3
/
lists
/
{list_uuid}
/
entries
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"}'

{
  "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"
}
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-2 or alpha-3 country code
  • face, document, wallet_address, bank_account, user, business, key: Any non-empty string
For face entries, use the Upload face endpoint instead — unless you provide a reference_session_id, which handles face blocklisting automatically (including biometric matching).

​
Request body

FieldTypeRequiredDescription
valuestringConditionalThe 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_idstring (UUID)NoVerification 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.
reference_object_uuidstring (UUID)NoUUID 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_labelstringNoHuman-readable label shown in the console
commentstringNoComment or reason for adding
metadataobjectNoAdditional 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. 
{
  "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: 
{
  "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 entityreference_object_uuidmetadata.reference_type
Verification sessionAuto-set by backend (face/KYC/phone/email UUID)Not needed — use reference_session_id
TransactionTransaction UUID"transaction"
Vendor userdidit_internal_id"vendor_user"
Vendor businessdidit_internal_id"vendor_business"
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"}'

{
  "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"
}