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>",
  "doubleCheckRenaper": true,
  "documentNumber": "<string>",
  "gender": "<string>",
  "personalNumber": "<string>"
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Resumen

Face Match es un servicio de verificación de Gu1 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 Gu1).
  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 Gu1. Toda la verificación se realiza en la infraestructura de Gu1.

​
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.
​
doubleCheckRenaper
boolean
Con true, tras aprobar el face match de Gu1 ejecuta RENAPER biométrico (validate-dni con la selfie) y datos (renaper/data: DNI + trámite). Requiere credenciales RENAPER de la org y integraciones Marketplace activas: ar_renaper_data_enrichment y ar_renaper_validate_dni_enrichment. El query prevalece sobre el body.
​
doubleCheckRenaper
boolean
Igual que el query param doubleCheckRenaper.
​
documentNumber
string
DNI para RENAPER cuando doubleCheckRenaper=true. Opcional si entityId resuelve taxId o person.idNumber.
​
gender
string
Género para RENAPER (M, F, male, female). Obligatorio salvo resolución desde entidad vinculada.
​
personalNumber
string
required
Número de trámite para el chequeo RENAPER. Obligatorio con doubleCheckRenaper=true.
El umbral mínimo (threshold) puede enviarse en el form; si no se envía, se lee de la configuración KYC de la organización. La respuesta incluye el umbral que se usó en la llamada.

​
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 (soporte y listado).
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 de la verificación (p. ej. LOW_FACE_MATCH_SIMILARITY, NO_REFERENCE_IMAGE). Ver Códigos de riesgo en advertencias para todos los valores.
doubleCheckRenaperboolean (opcional)true si se solicitó doble chequeo RENAPER.
responseDoubleChecksobject (opcional)Con doubleCheckRenaper=true: renaper (datos/trámite) y renaperBiometric (ABIS). Misma forma que KYC validations RENAPER.
Si falla RENAPER tras aprobación del proveedor, match pasa a false, status a "declined" y se añaden códigos RENAPER a warnings. Usá timeout HTTP ≥ 60 s con double-check. Ejemplo: 
{
  "match": true,
  "score": 85.5,
  "status": "approved",
  "verificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scoreDeclineThreshold": 30,
  "requestId": "req_xyz",
  "warnings": []
}

​
Ejemplo de solicitud

const form = new FormData();
form.append('documentImage', documentFile); // File object
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();
console.log('Match:', result.match, 'Score:', result.score);

​
Respuestas de error

Códigos de error habituales:
CódigoHTTPSignificado
NOT_CONFIGURED403Credenciales Face Match no configuradas en la organización.
NOT_ENABLED403Integración Face Match no activada para esta organización.
INVALID_REQUEST400Content-Type no es multipart/form-data, o faltan/imágenes inválidas (p. ej. sin archivo ni base64 para un campo obligatorio, formato/tamaño).
UNAUTHORIZED401Credenciales de API/verificación inválidas o faltantes.
QUOTA_EXCEEDED403No se pudo completar la verificación (p. ej. cuota/créditos).
SERVICE_UNAVAILABLE503Servicio de verificación temporalmente no disponible.
VERIFICATION_FAILED500No se pudo completar la verificación; reintentar u otras imágenes.

​
Auditoría y listado de verificaciones

Cada solicitud de Face Match (éxito o fallo) se guarda en face_match_verifications para auditoría y cumplimiento. La respuesta incluye verificationId (ID del registro de auditoría). Cada registro guardado también almacena el umbral usado en el momento de la llamada (para mostrarlo en el historial aunque cambie el umbral de la org).

​
Listar registros de auditoría

GET https://api.gu1.ai/api/kyc/face-match/verifications?entityId={entityId}&limit=50&offset=0
Parámetros de query:
ParámetroTipoDescripción
entityIdstring (UUID)Opcional. Filtrar por entidad persona.
statusstringOpcional. Filtrar por estado (approved, declined, in_review, failed).
limitnumberMáximo de ítems (por defecto 50, máx. 100).
offsetnumberDesplazamiento de paginación.
Respuesta: { "verifications": [ ... ], "scoreDeclineThreshold": 30, "pagination": { "limit", "offset", "total" } }. Cada verificación incluye id, entityId, status, match, score, threshold (valor usado en esa ejecución), createdAt y rutas de imagen opcionales para auditoría.

​
Obtener verificación por ID

Obtiene un registro de auditoría de Face Match por su verificationId (devuelto en la respuesta del POST o en el listado). 
GET https://api.gu1.ai/api/kyc/face-match/verifications/:id
Parámetro de path: id — UUID de la verificación (igual que verificationId del POST o del listado). Respuesta (200): Un objeto de verificación con los mismos campos que cada ítem del listado: id, organizationId, entityId, status, match, score, requestId, vendorData, errorMessage, triggeredByUserId, createdAt, documentStoragePath, selfieStoragePath, storageProvider, threshold. Errores: 404 NOT_FOUND si el ID no existe o pertenece a otra organización; 401 UNAUTHORIZED si no estás autenticado.

​
Convivencia con KYC por sesión

  • Flujo por sesión crea un registro en kyc_validations, envía al usuario a una URL alojada y actualiza el estado vía webhooks. La decisión almacenada incluye documento, liveness y face match de la sesión en vivo.
  • Face Match crea un registro de auditoría en face_match_verifications y devuelve el resultado en la misma solicitud. No crea un registro en kyc_validations. Usalo cuando necesitás una verificación puntual (p. ej. «¿estas dos imágenes son la misma persona?») sin sesión alojada.
  • Ambos usan la misma configuración KYC de la organización. El umbral de Face Match se define en Configuración de la organización → KYC (tarjeta Face Match).

​
Próximos pasos

Crear validación KYC

Verificación por sesión con URL alojada

Listar validaciones

Listar validaciones KYC por entidad