Skip to main content
POST
/
api
/
kyc
/
face-match
Face Match (Documento + Selfie)
curl --request POST \
  --url http://api.gu1.ai/api/kyc/face-match \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentImage": {},
  "selfieImage": {},
  "entityId": "<string>",
  "scoreThreshold": 123,
  "vendorData": "<string>"
}
'

​
Resumen

Face Match es un servicio de verificación de Gueno que compara dos imágenes: una selfie (foto actual de la persona) y una imagen de referencia del documento (por ejemplo el retrato del DNI). La API devuelve si las caras coinciden (misma persona) y una puntuación de similitud. No hay sesión alojada ni detección de vida en tiempo real: enviás las imágenes y obtenés el resultado en una sola llamada.
Cuándo usar cada uno
  • KYC por sesión (POST /api/kyc/validations): Flujo completo con URL alojada, selfie en vivo, liveness y captura de documento. Ideal para onboarding y flujos regulados.
  • Face Match (POST /api/kyc/face-match): Enviás dos imágenes (como archivos o base64) y recibís coincidencia + puntuación. Ideal cuando ya tenés documento y selfie (por ejemplo desde tu propia app).

​
Prerrequisitos

Antes de usar Face Match:
  1. Integración Face Match activada: Tu organización debe tener la integración KYC Face Match activada (por ejemplo en Marketplace / Integraciones).
  2. Credenciales configuradas: La API key y el webhook secret de la integración Face Match deben estar configurados en la configuración KYC de la organización (lo define el administrador de Gueno).
  3. Umbral (opcional): El puntaje mínimo para aprobar (0–100) se configura en Configuración de la organización → KYC (tarjeta Face Match). Si no se define, el valor por defecto es 30. Solo los administradores de la organización pueden cambiar este valor.
Face Match es un servicio de Gueno. Toda la verificación se realiza en nuestra infraestructura; no se exponen nombres de proveedores externos en las respuestas ni en los mensajes de error.

​
Solicitud

​
Endpoint

POST https://api.gu1.ai/api/kyc/face-match

​
Content-Type

Solo se acepta multipart/form-data. Podés enviar las imágenes de dos formas (o combinar):
  1. Como archivos: adjuntar archivos de imagen en los campos del form documentImage y selfieImage.
  2. Como cadenas base64: enviar los mismos nombres de campo con la imagen en base64 (con o sin prefijo data:image/...;base64,).
Si falta una imagen obligatoria (ni archivo ni base64 para ese campo), la API devuelve 400. Para cada imagen, si enviás archivo y base64, se usa el archivo.

​
Headers

Authorization: Bearer TU_API_KEY
Content-Type: multipart/form-data; boundary=----...
No definas Content-Type a mano al usar FormData; el cliente lo setea con el boundary correcto. Si tu cuenta usa organización, incluí: 
X-Organization-Id: TU_ORGANIZATION_ID

​
Campos del form

​
documentImage
file | string
required
Imagen de referencia (por ejemplo el retrato del documento). Enviar como archivo (recomendado) o como string (base64, con o sin prefijo data:image/...;base64,). Formatos: JPEG, PNG, WebP, TIFF. Máx. 5MB.
​
selfieImage
file | string
required
Imagen de la selfie. Igual que documentImage: archivo o base64. Obligatorio.
​
entityId
string
UUID opcional de la entidad persona a asociar con esta verificación. Se usa para auditoría y para listar verificaciones por entidad.
​
scoreThreshold
number
Opcional. Umbral 0–100; resultados por debajo se rechazan. Si se omite, se usa el umbral configurado en la organización (o 30 por defecto).
​
vendorData
string
Referencia opcional (por ejemplo tu ID de usuario) para trazabilidad. Se guarda en el registro de auditoría.

​
Respuesta

​
Respuesta exitosa (200 OK)

CampoTipoDescripción
matchbooleanSi las caras se consideraron coincidentes (puntuación ≥ umbral).
scorenumberPuntuación de similitud 0–100.
statusstring"approved" | "declined" | "in_review".
verificationIdstringID del registro de auditoría en face_match_verifications.
scoreDeclineThresholdnumberUmbral (0–100) usado en esta verificación (configuración de la org).
requestIdstring (opcional)ID interno de la solicitud (soporte).
warningsstring[] (opcional)Array de códigos de riesgo (p. ej. LOW_FACE_MATCH_SIMILARITY, NO_REFERENCE_IMAGE). Ver Códigos de riesgo en advertencias.

​
Ejemplo de solicitud

const form = new FormData();
form.append('documentImage', documentFile);
form.append('selfieImage', selfieFile);
form.append('entityId', '123e4567-e89b-12d3-a456-426614174000');

const response = await fetch('https://api.gu1.ai/api/kyc/face-match', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer TU_API_KEY' },
  body: form,
});
const result = await response.json();

​
Errores

CódigoHTTPSignificado
NOT_CONFIGURED403Credenciales Face Match no configuradas en la organización.
NOT_ENABLED403Integración Face Match no activada.
INVALID_REQUEST400Content-Type no es multipart/form-data o faltan/imagen inválida (sin archivo ni base64 para un campo obligatorio).
UNAUTHORIZED401Credenciales inválidas o faltantes.
VERIFICATION_FAILED500Fallo genérico; reintentar u otras imágenes.

​
Auditoría y listado

Cada solicitud se guarda en face_match_verifications. Para listar: 
GET https://api.gu1.ai/api/kyc/face-match/verifications?entityId={entityId}&limit=50&offset=0
Para obtener una verificación por ID: 
GET https://api.gu1.ai/api/kyc/face-match/verifications/:id

​
Próximos pasos

Crear validación KYC

Verificación por sesión con URL alojada

Face Match (Documento + Selfie)

Comparar documento y selfie