Crear entrada de lista por API: bloqueo y permitidos

curl

curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"value": "+14155552671", "comment": "Reported fraud"}'

from didit import Didit

# Reads DIDIT_API_KEY.
client = Didit()

result = client.lists.entries.create(
    "11111111-2222-3333-4444-555555555555",
    value="+14155552671",
    comment="Reported fraud",
)
print(result)

import Didit from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.lists.entries.create("11111111-2222-3333-4444-555555555555", {
  value: "+14155552671",
  comment: "Reported fraud",
});
console.log(result);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Lists.Entries.Create(ctx, "11111111-2222-3333-4444-555555555555", didit.ListsEntriesCreateParams{
	Value:   didit.String("+14155552671"),
	Comment: didit.String("Reported fraud"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.ListsEntriesCreateParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.lists().entries().create("11111111-2222-3333-4444-555555555555", ListsEntriesCreateParams.builder()
        .value("+14155552671")
        .comment("Reported fraud")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->lists->entries->create('11111111-2222-3333-4444-555555555555', [
    'value' => '+14155552671',
    'comment' => 'Reported fraud',
]);
print_r($result->toArray());

require "didit"

# Reads DIDIT_API_KEY.
didit = Didit::Client.new

result = didit.lists.entries.create(
  "11111111-2222-3333-4444-555555555555",
  value: "+14155552671",
  comment: "Reported fraud"
)
puts result.to_h

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.Lists.Entries.CreateAsync("11111111-2222-3333-4444-555555555555", new ListsEntriesCreateParams
{
    Value = "+14155552671",
    Comment = "Reported fraud",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "value": "+14155552671",
  "display_label": "",
  "comment": "Reported fraud",
  "added_by": "api",
  "reference_session_id": null,
  "reference_session_number": null,
  "reference_session_type": null,
  "reference_object_uuid": null,
  "metadata": null,
  "created_at": "2026-10-12T10:04:51.220391Z"
}

POST

lists

{list_uuid}

entries

curl

curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"value": "+14155552671", "comment": "Reported fraud"}'

from didit import Didit

# Reads DIDIT_API_KEY.
client = Didit()

result = client.lists.entries.create(
    "11111111-2222-3333-4444-555555555555",
    value="+14155552671",
    comment="Reported fraud",
)
print(result)

import Didit from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.lists.entries.create("11111111-2222-3333-4444-555555555555", {
  value: "+14155552671",
  comment: "Reported fraud",
});
console.log(result);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Lists.Entries.Create(ctx, "11111111-2222-3333-4444-555555555555", didit.ListsEntriesCreateParams{
	Value:   didit.String("+14155552671"),
	Comment: didit.String("Reported fraud"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.ListsEntriesCreateParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.lists().entries().create("11111111-2222-3333-4444-555555555555", ListsEntriesCreateParams.builder()
        .value("+14155552671")
        .comment("Reported fraud")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->lists->entries->create('11111111-2222-3333-4444-555555555555', [
    'value' => '+14155552671',
    'comment' => 'Reported fraud',
]);
print_r($result->toArray());

require "didit"

# Reads DIDIT_API_KEY.
didit = Didit::Client.new

result = didit.lists.entries.create(
  "11111111-2222-3333-4444-555555555555",
  value: "+14155552671",
  comment: "Reported fraud"
)
puts result.to_h

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.Lists.Entries.CreateAsync("11111111-2222-3333-4444-555555555555", new ListsEntriesCreateParams
{
    Value = "+14155552671",
    Comment = "Reported fraud",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "value": "+14155552671",
  "display_label": "",
  "comment": "Reported fraud",
  "added_by": "api",
  "reference_session_id": null,
  "reference_session_number": null,
  "reference_session_type": null,
  "reference_object_uuid": null,
  "metadata": null,
  "created_at": "2026-10-12T10:04:51.220391Z"
}

Añade una entrada a una lista. El valor se valida según el tipo de entrada de la lista:

email: una dirección de correo electrónico válida
phone: un número de teléfono internacional válido, almacenado en formato E.164 (por ejemplo, +14155552671)
ip_address: una dirección IP o un rango CIDR válidos (p. ej., 192.168.1.1 o 10.0.0.0/8)
device_fingerprint: al menos 8 caracteres entre letras, dígitos, -, _, : y .. Una lista de bloqueo rechaza una huella digital que hayan reportado varios dispositivos distintos, porque bloquearla rechazaría a personas que no tienen relación entre sí.
country: un código de país ISO 3166-1 alfa-3 válido (p. ej., USA, GBR, ESP). Los códigos alfa-2 (p. ej., US) se aceptan y se convierten automáticamente a alfa-3.
user, business: el vendor_data del usuario o de la empresa
face, document, wallet_address, bank_account, key: cualquier cadena no vacía

Todos los valores de las entradas no distinguen entre mayúsculas y minúsculas. Los valores que envías se normalizan al almacenarse (los números de teléfono a E.164, los códigos de país a mayúsculas y todo lo demás a minúsculas) y se comparan sin distinguir entre mayúsculas y minúsculas durante la verificación. Por ejemplo, bloquear User@Example.COM también detectará user@example.com. Una lista contiene cada valor una sola vez: añadir un valor que ya está en la lista devuelve 400.

Para un rostro, usa Subir rostro cuando solo tengas una imagen, o envía un reference_session_id para tomar el rostro de una sesión existente. Una entrada de rostro necesita un rostro almacenado con el que comparar, algo que un value escrito no proporciona.

Añadir desde una sesión

Cuando proporcionas un reference_session_id, Didit:

Busca la sesión (debe pertenecer a la misma aplicación)
Lee el valor del registro más reciente de la sesión del tipo de entrada de la lista:
- face: el rostro de la selfie de prueba de vida; value es el UUID del rostro
- document: el número de documento; el nombre completo, el estado emisor, el tipo de documento, la región y el número de documento se almacenan en metadata, y display_label toma por defecto el nombre del titular y el número de documento
- phone: el número de teléfono
- email: la dirección de correo electrónico
- ip_address: la dirección IP de la sesión
- device_fingerprint: una huella de dispositivo que identifica un único dispositivo, con preferencia por un dispositivo que haya completado un paso de verificación. En una lista de bloqueo, Didit rechaza una sesión que solo tiene una huella de clase de dispositivo o que se completó en más de un dispositivo: en ese caso, envía la huella exacta como value.
Vincula la entrada a la sesión (reference_session_id) y al registro (reference_object_uuid) para garantizar la trazabilidad

En las listas de bloqueo del sistema de rostros, documentos, teléfonos y correos electrónicos, el registro también se marca como bloqueado, de modo que las nuevas sesiones que coincidan con él se rechazan. Para cualquier otro tipo de entrada, envía también value. Devuelve 400 si no se encuentra la sesión o si no contiene datos del tipo de entrada solicitado.

Rostros de la selfie de captura del documento

Mientras el usuario fotografía su documento, la cámara frontal puede tomarle una selfie (las imágenes front_image_camera_front y back_image_camera_front del informe de verificación de identidad). Ese rostro se puede añadir a la lista de bloqueo de rostros además del rostro de la prueba de vida: pasa face_image_source con la imagen que quieras.

{
  "reference_session_id": "33333333-4444-5555-6666-777777777777",
  "face_image_source": "front_image_camera_front"
}

La entrada se crea solo en la lista de bloqueo de rostros del sistema, y value debe dejarse vacío: Didit toma el rostro de la selfie de la sesión.
La selfie debe contener un único rostro nítido. Si no es así, la solicitud devuelve 400 y no se añade nada.
Cada selfie se puede añadir una sola vez. Los campos metadata.face_image_source y metadata.reference_node_id de la entrada indican de qué selfie procede.
En un flujo de verificación (workflow) con más de un paso de verificación de identidad, reference_node_id elige el paso cuya selfie se usa. Por defecto, Didit usa la verificación de identidad más reciente que tenga esa selfie.
A partir de entonces, el rostro se comprueba como cualquier otro rostro bloqueado: con la selfie de prueba de vida de cada nueva sesión y con cada nueva selfie de captura del documento (consulta FRONT_CAMERA_FACE_IN_BLOCKLIST).
Eliminar la entrada quita el rostro de la lista de bloqueo, y deja de coincidir con nuevas sesiones.

Sesiones con varios registros del mismo tipo

Una sesión puede contener más de un registro de un tipo, por ejemplo dos números de teléfono de un flujo de varios pasos. Didit siempre lee el más reciente. Si envías value junto con reference_session_id, la entrada almacena tu value, pero sigue vinculada a ese registro más reciente, y en una lista de bloqueo del sistema es ese registro el que se marca. Para incluir en la lista un valor de un registro anterior, añádelo solo con value, sin reference_session_id:

{
  "value": "+34612345678",
  "comment": "First phone number of session 42"
}

Referenciar transacciones, usuarios y empresas

Al bloquear datos de una transacción o de un usuario o empresa del proveedor, pasa el UUID de la entidad como reference_object_uuid e indica el tipo de origen en metadata:

{
  "value": "0x52908400098527886E0F7030069857D2E4169EE7",
  "reference_object_uuid": "55555555-6666-7777-8888-999999999999",
  "metadata": {
    "reference_type": "transaction",
    "reference_id": "55555555-6666-7777-8888-999999999999"
  }
}

Esto te permite navegar desde la entrada de la lista de bloqueo hasta la transacción, el usuario o la empresa originales en la consola. Didit almacena tus claves de metadata, excepto reference_image_url y front_image_url, que solo establece Didit. En una entrada obtenida de una sesión, Didit añade sus propias claves a las tuyas, y las suyas prevalecen.

Entidad de origen	`reference_object_uuid`	`metadata.reference_type`
Sesión de verificación	Lo establece Didit (el registro facial, documento, teléfono o correo electrónico)	No es necesario: usa `reference_session_id`
Transacción	UUID de la transacción	`"transaction"`
Usuario del proveedor	`didit_internal_id`	`"vendor_user"`
Empresa del proveedor	`didit_internal_id`	`"vendor_business"`

En las listas de bloqueo del sistema User y Business, Didit también marca como BLOCKED a los usuarios o empresas coincidentes: aquellos cuyo vendor_data sea igual a value, o cuyo didit_internal_id sea igual a reference_object_uuid. Consulta Lista de bloqueo de usuarios y Lista de bloqueo de empresas.

Autorizaciones

x-api-key

string

header

requerido

La clave de API de tu aplicación, que encontrarás en Developers -> API keys en la Business Console. La clave principal tiene acceso completo. Una clave con nombre puede tener un alcance limitado: ninguno, lectura o escritura por recurso, limitada a algunos flujos o a sesiones aprobadas, a una lista de direcciones IP y a una fecha de caducidad. 401 significa que la clave es incorrecta, se revocó o expiró; 403 significa que no se envió ninguna clave, que la clave no tiene acceso a este recurso o acción, o que la solicitud provino de una dirección fuera de su lista de IP; 404 en una ruta de sesión significa que la sesión está fuera de los flujos o estados de la clave. Una clave sin acceso a contenido multimedia recibe las URL de imágenes, videos y PDF como null, y una clave sin permiso de escritura en sesiones recibe los enlaces y tokens de sesión como null. Consulta https://docs.didit.me/console/api-keys.

Parámetros de ruta

list_uuid

string<uuid>

requerido

UUID de la lista a la que se añade. Para un rostro del que solo tienes una imagen, usa en su lugar Subir un rostro a una lista.

Cuerpo

application/json

Envía value, reference_session_id o ambos. Los campos que aplican dependen del entry_type de la lista.

value

string

El valor que se añade a la lista, validado según el entry_type de la lista: email, una dirección de correo electrónico válida; phone, un número internacional válido, almacenado en E.164; ip_address, una dirección IP o un rango CIDR (por ejemplo, 10.0.0.0/8); device_fingerprint, al menos 8 caracteres entre letras, dígitos, -, _, : y . (una lista de bloqueo rechaza una huella digital que hayan reportado varios dispositivos distintos); country, un código ISO 3166-1 alfa-2 o alfa-3, almacenado como alfa-3; user y business, el vendor_data; cualquier otro tipo, una cadena no vacía. Se almacena en minúsculas, salvo los números de teléfono y los códigos de país, y una lista contiene cada valor una sola vez (sin distinguir mayúsculas de minúsculas). Obligatorio salvo que se envíe reference_session_id; debe dejarse vacío con un face_image_source de captura de documento.

reference_session_id

string<uuid>

Una sesión de verificación de persona o de empresa de tu aplicación de la que tomar el valor. Didit lee el registro más reciente de la sesión del tipo de entrada de la lista (face, document, phone, email, ip_address o device_fingerprint), vincula la entrada a la sesión y a ese registro, y rellena display_label y metadata para los documentos. En una lista de bloqueo device_fingerprint, se rechaza una sesión que solo tiene una huella de clase de dispositivo, o que se completó en más de un dispositivo: envía la huella exacta como value. Para otros tipos de entrada, o cuando la sesión no tiene ese registro, envía también value; en ese caso se almacena tu value y la entrada sigue vinculada a la sesión.

reference_object_uuid

string<uuid>

UUID del registro que representa la entrada cuando no procede de una sesión: un UUID de transacción o el didit_internal_id de un usuario o una empresa. Combínalo con metadata.reference_type. Se sustituye por el registro de la sesión cuando reference_session_id aporta uno.

face_image_source

enum<string>

predeterminado:liveness

Listas de rostros con reference_session_id: indica de cuál de las imágenes de la sesión se toma el rostro. liveness (valor predeterminado) es la selfie de la prueba de vida. front_image_camera_front y back_image_camera_front son las selfies que tomó la cámara frontal mientras el usuario fotografiaba el anverso o el reverso de su documento: solo se aceptan en la lista de bloqueo de rostros del sistema, con reference_session_id y un value vacío. Cada selfie puede añadirse una sola vez y debe mostrar un único rostro nítido.

Opciones disponibles:

liveness,

front_image_camera_front,

back_image_camera_front

reference_node_id

string | null

Con un face_image_source de captura de documento: el nodo de verificación de identidad cuya selfie se usará, para flujos con más de uno. De forma predeterminada, la verificación de identidad más reciente que tenga esa imagen. Se rechaza con liveness.

Maximum string length: 100

display_label

string

Etiqueta legible. Si está vacía, Didit genera una a partir de la sesión cuando es posible (por ejemplo, el nombre del titular y el número de documento).

Maximum string length: 512

comment

string

Nota en texto libre, como el motivo de la inclusión en la lista.

metadata

object

JSON libre que se guarda con la entrada y se devuelve tal como se guardó. Usa reference_type y reference_id para que la consola enlace al origen. reference_image_url y front_image_url solo los establece Didit y se descartan si los envías. En una entrada leída de una sesión, las claves de Didit se combinan con las tuyas.

Show child attributes

Respuesta

Se creó la entrada.

Un valor de una lista.

uuid

string<uuid>

requerido

Identificador de la entrada. Úsalo como entry_uuid en Eliminar una entrada de lista.

value

string

requerido

El valor incluido en la lista: un número de teléfono en formato E.164, una dirección de correo electrónico, un número de documento, una dirección IP o un rango CIDR, una huella de dispositivo, una dirección de wallet, una cuenta bancaria, un código de país ISO 3166-1 alfa-3, un vendor_data, cualquier cadena en una lista key, o el UUID del rostro almacenado en una lista de rostros. Los valores que envías se almacenan en minúsculas, excepto los números de teléfono y los códigos de país. La coincidencia no distingue entre mayúsculas y minúsculas.

display_label

string | null

requerido

Etiqueta legible. Didit la completa en las entradas tomadas de una sesión (por ejemplo, el nombre del titular y el número de documento) cuando no envías ninguna.

Maximum string length: 512

comment

string

requerido

Nota en texto libre. Cadena vacía cuando no está definida.

added_by

string | null

requerido

Quién añadió la entrada: api (una clave de API), el correo electrónico de un usuario de la consola o console, system o migration (entradas creadas por Didit), o rule (una acción de una regla de transacciones o de monitorización).

reference_session_id

string<uuid> | null

requerido

Sesión de verificación de la que se tomó la entrada. null cuando la entrada se añadió por valor.

reference_session_number

integer | null

requerido

Número de esa sesión dentro de la aplicación, tal como se muestra en la consola.

reference_session_type

enum<string> | null

requerido

kyc para una sesión de verificación de una persona, kyb para una sesión de verificación de una empresa, null cuando no hay sesión.

Opciones disponibles:

kyc,

kyb,

null

reference_object_uuid

string<uuid> | null

requerido

El registro que representa la entrada: el registro de rostro, documento, teléfono o correo electrónico leído de una sesión, el rostro creado con Subir un rostro a una lista, o el UUID que enviaste (por ejemplo, el UUID de una transacción o el didit_internal_id de un usuario).

metadata

object | null

requerido

Contexto adicional. Contiene las claves que establece Didit (enumeradas aquí) combinadas con cualquier metadata que enviaste al crear la entrada, devueltas tal como se almacenaron. null cuando no hay ninguna.

Show child attributes

created_at

string<date-time>

requerido

Cuándo se añadió la entrada.

Última modificación el 1 de noviembre de 2026

​Añadir desde una sesión

​Rostros de la selfie de captura del documento

​Sesiones con varios registros del mismo tipo

​Referenciar transacciones, usuarios y empresas

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

Añadir desde una sesión

Rostros de la selfie de captura del documento

Sesiones con varios registros del mismo tipo

Referenciar transacciones, usuarios y empresas