Saltar al contenido principal
POST
cURL

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.

Cuerpo

multipart/form-data
user_image
file
requerido

Imagen frontal del rostro con la que buscar. Extensiones permitidas: tiff, jpg, jpeg, png, webp. Tamaño máximo de carga: 5 MB (los archivos más grandes se rechazan con 400). Las imágenes se comprimen automáticamente a ~0.5 MB antes del procesamiento, por lo que las resoluciones muy altas no mejoran la precisión. La imagen debe contener al menos un rostro detectable; de lo contrario, el endpoint devuelve 400. Cuando hay varios rostros, se busca el más grande y se añade una advertencia MULTIPLE_FACES_DETECTED.

search_type
enum<string>
predeterminado:most_similar

Política de búsqueda. most_similar (predeterminado) ordena por similitud todos los rostros registrados en tu aplicación. blocklisted_or_approved limita los candidatos a rostros en la lista de bloqueo, rostros en la lista de permitidos, rostros de sesiones aprobadas y rostros de perfiles de usuario importados, con las entradas de la lista de bloqueo en primer lugar.

Opciones disponibles:
most_similar,
blocklisted_or_approved
Ejemplo:

"most_similar"

rotate_image
boolean
predeterminado:false

Si es true, el servicio prueba rotaciones de 90 grados de la entrada y usa la orientación que ofrece la mejor detección facial. Útil cuando falta la orientación EXIF. Añade latencia.

Ejemplo:

false

save_api_request
boolean
predeterminado:true

Si es true (valor predeterminado), guarda la llamada como una sesión de tipo API, emite un webhook status.updated, genera URL prefirmadas para los valores de match_image_url y registra el rostro buscado en tu índice de búsqueda facial (los registros de Búsqueda facial se excluyen de búsquedas futuras). Si es false, la búsqueda es puntual: no se almacena ninguna sesión y el rostro no se registra.

Ejemplo:

true

vendor_data
string

Identificador opaco opcional (tu ID de usuario, correo electrónico, UUID…) que se guarda en la sesión persistida y se devuelve. No excluye de los resultados de la búsqueda los rostros del mismo usuario.

Ejemplo:

"user-123"

metadata
object

Objeto JSON opcional que se almacena con la sesión (cuando save_api_request=true) y se devuelve. En solicitudes multipart, envíalo como un campo de cadena codificado en JSON: se convierte en un objeto.

Ejemplo:

Respuesta

Búsqueda facial completada. face_search.matches contiene hasta 5 rostros similares ordenados por similitud; un array vacío significa que ningún rostro registrado superó el umbral mínimo de similitud. status es Declined solo cuando hay coincidencias en la lista de bloqueo: las coincidencias duplicadas por sí solas devuelven Approved, así que revisa matches y warnings, no solo status. Cuando save_api_request=true, request_id es el ID de la sesión guardada. Cada coincidencia incluye source (session, imported, list_entry o retained_template), vendor_user_id y biometric_template_id; una coincidencia retained_template procede de una plantilla biométrica sin imagen que se conservó después de que se eliminara la sesión de origen, y tiene null en los campos de sesión, match_image_url y user_details.

request_id
string<uuid>

ID de la sesión guardada cuando save_api_request=true (se puede usar con GET /v3/session/{sessionId}/decision/); en caso contrario, un UUID de correlación temporal.

vendor_data
string | null

Devuelve el vendor_data que enviaste, o null.

metadata
object | null

Devuelve el objeto metadata que enviaste, o null.

created_at
string<date-time>

Marca de tiempo ISO 8601 (UTC) del momento en que se generó la respuesta, p. ej., 2026-06-12T01:04:42.763237+00:00.

Última modificación el 1 de noviembre de 2026