Saltar al contenido principal
POST
curl
Sube una imagen de rostro codificada en base64 a una lista de bloqueo o lista de permitidos de rostros. Didit detecta los rostros de la imagen, conserva el más grande, almacena la imagen y un recorte de ese rostro, y calcula la plantilla biométrica facial con la que se comparan las nuevas sesiones. El value de la nueva entrada es el UUID de ese rostro. Solo está disponible para listas con entry_type: face y list_type: blocklist o list_type: allowlist.
Si vas a añadir a una lista de bloqueo o de permitidos un rostro de una sesión existente, usa Crear entrada con reference_session_id: así la entrada queda vinculada a la sesión.
La imagen debe contener un rostro claramente visible y ocupar como máximo 2 MB una vez decodificada. Si no se detecta ningún rostro, la solicitud devuelve 400 y no se crea ninguna entrada. Si el análisis facial no está disponible temporalmente, devuelve 503: vuelve a intentarlo más tarde.
Para quitar el rostro de la lista, elimina su entrada: dejará de coincidir con nuevas sesiones.

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 una lista con entry_type: face y list_type: blocklist o allowlist.

Cuerpo

application/json
image
string<byte>
requerido

Imagen JPEG o PNG codificada en base64, de 2 MB como máximo una vez decodificada, que muestre un rostro claramente visible. Envía solo la cadena base64, sin el prefijo data:image/...;base64,.

comment
string
predeterminado:""

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

Respuesta

Se creó la entrada del rostro.

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.

created_at
string<date-time>
requerido

Cuándo se añadió la entrada.

Última modificación el 1 de noviembre de 2026