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 del rostro real o candidato que se va a verificar (p. ej., una selfie). Envía una única foto de frente con el rostro de la persona claramente visible y bien iluminado. Extensiones permitidas: tiff, jpg, jpeg, png, webp. Tamaño máximo de subida: 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.

ref_image
file
requerido

Imagen facial de referencia con la que comparar (p. ej., el retrato de un documento de identidad o una foto registrada previamente). Tiene los mismos límites de formato y tamaño que user_image.

face_match_score_decline_threshold
number<float>
predeterminado:30

Umbral de similitud (0–100) que determina el status de la respuesta. Una puntuación calculada igual o inferior a este valor establece status en Declined y añade una advertencia LOW_FACE_MATCH_SIMILARITY; una puntuación estrictamente superior devuelve Approved. El valor predeterminado 30 es permisivo: súbelo (p. ej., 50–60) para una verificación más estricta. Los valores fuera de 0–100 devuelven 400.

Rango requerido: 0 <= x <= 100
Ejemplo:

50

rotate_image
boolean
predeterminado:false

Si es true, el servicio prueba las imágenes de entrada en incrementos de 90 grados (0, 90, 180, 270) y usa la orientación que ofrece la mejor detección facial, algo útil para capturas desde el móvil sin orientación EXIF. Añade latencia, así que actívalo solo si no puedes garantizar imágenes en posición vertical.

Ejemplo:

false

save_api_request
boolean
predeterminado:true

Cuando es true (valor predeterminado), guarda la llamada como una sesión de tipo API: visible en la Business Console, recuperable mediante GET /v3/session/{sessionId}/decision/ con el request_id devuelto y notificada mediante un webhook status.updated. Cuando es false, no se almacena nada y request_id es un UUID temporal que solo sirve para correlacionar la respuesta.

Ejemplo:

true

vendor_data
string

Cadena opaca opcional (tu ID de usuario interno, correo electrónico, UUID…) que se guarda en la sesión persistida y se devuelve en la respuesta. Úsala para relacionar las llamadas a la API con tus propios registros y para filtrar sesiones más adelante.

Ejemplo:

"user-123"

metadata
object

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

Ejemplo:

Respuesta

Coincidencia facial calculada. face_match.score es un número decimal de 0 a 100 (dos decimales); status es Approved cuando la puntuación es estrictamente superior a face_match_score_decline_threshold; en caso contrario, es Declined con una advertencia explicativa. Una similitud baja o un par imposible de puntuar también devuelve 200: revisa face_match.status y face_match.warnings, no solo el código HTTP. Cuando save_api_request=true, request_id es el ID de la sesión guardada.

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.

face_match
object
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