Skip to main content
POST
/
api
/
kyc
/
id-verification
ID Verification (Frente/Reverso del documento)
curl --request POST \
  --url http://api.gu1.ai/api/kyc/id-verification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentFront": {},
  "documentBack": {},
  "entityId": "<string>",
  "vendorData": "<string>",
  "performDocumentLiveness": true,
  "minimumAge": 123,
  "expirationDateNotDetectedAction": "<string>",
  "invalidMrzAction": "<string>",
  "inconsistentDataAction": "<string>"
}
'

​
Resumen

ID Verification es un servicio de verificación de Gueno que valida un documento de identidad enviando la imagen del frente (obligatoria) y opcionalmente la imagen del reverso (para documentos de dos caras como DNI). La API devuelve Aprobado o Rechazado, datos extraídos (nombre, número de documento, fecha de nacimiento, dirección, MRZ, etc.) y advertencias opcionales. No hay sesión alojada: enviás las imágenes y obtenés el resultado en una llamada.
Cuándo usar cada uno
  • KYC por sesión (POST /api/kyc/validations): Flujo completo con URL alojada, selfie en vivo y captura de documento.
  • Face Match (POST /api/kyc/face-match): Comparar retrato del documento y selfie; devuelve coincidencia + puntuación.
  • ID Verification (POST /api/kyc/id-verification): Enviar frente (y opcional reverso) del documento; obtener validación, datos extraídos y Aprobado/Rechazado. Ideal cuando ya tenés las imágenes del documento.

​
Prerrequisitos

  1. Integración ID Verification activada en la organización.
  2. API key configurada en la configuración KYC de la organización.

​
Solicitud

​
Endpoint

POST https://api.gu1.ai/api/kyc/id-verification

​
Content-Type

Solo se acepta multipart/form-data. Podés enviar imágenes de dos formas:
  1. Como archivos: adjuntar en los campos documentFront y (opcional) documentBack.
  2. Como base64: enviar los mismos nombres de campo con la imagen en base64.
documentFront es obligatorio: hay que enviar archivo o base64. Si no llega ninguno, la API devuelve 400. documentBack es opcional. Si enviás archivo y base64 para un mismo campo, se usa el archivo.

​
Headers

Authorization: Bearer TU_API_KEY
Content-Type: multipart/form-data; boundary=----...
Incluir X-Organization-Id si la cuenta usa organización.

​
Campos del form

​
documentFront
file | string
required
Imagen del frente del documento. Enviar como archivo o como string (base64). Formatos: JPEG, PNG, WebP, TIFF, PDF. Máx. 5MB.
​
documentBack
file | string
Imagen del reverso (opcional). Mismo formato que documentFront.
​
entityId
string
UUID opcional de la entidad persona. Para auditoría y listado por entidad.
​
vendorData
string
Referencia opcional para trazabilidad.
​
performDocumentLiveness
boolean
Realizar liveness del documento (detectar pantalla/copia). Por defecto false. Enviar como string en el form.
​
minimumAge
number
Edad mínima (1–120); por debajo se rechaza. Opcional.
​
expirationDateNotDetectedAction
string
"NO_ACTION" o "DECLINE" si no se detecta fecha de vencimiento. Opcional.
​
invalidMrzAction
string
"NO_ACTION" o "DECLINE" si el MRZ es inválido. Opcional.
​
inconsistentDataAction
string
"NO_ACTION" o "DECLINE" si los datos visuales no coinciden con el MRZ. Opcional.

​
Respuesta (200 OK)

CampoTipoDescripción
statusstring"approved" | "declined".
verificationIdstring (opcional)ID del registro de auditoría.
requestIdstring (opcional)ID interno de la solicitud.
extractedDataobject (opcional)Datos extraídos: nombre, número de documento, fecha de nacimiento, etc.
warningsstring[] (opcional)Array de códigos de riesgo (p. ej. DOCUMENT_EXPIRED, POSSIBLE_DUPLICATED_USER). Ver Códigos de riesgo en advertencias para todos los valores.

​
Ejemplo de solicitud

const form = new FormData();
form.append('documentFront', documentFrontFile);
if (documentBackFile) form.append('documentBack', documentBackFile);
form.append('entityId', '123e4567-e89b-12d3-a456-426614174000');

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

​
Errores

CódigoHTTPSignificado
NOT_CONFIGURED403API key no configurada en la organización.
NOT_ENABLED403Integración ID Verification no activada.
INVALID_REQUEST400Content-Type no es multipart/form-data o falta/inválido el frente (sin archivo ni base64).
VERIFICATION_FAILED500Fallo genérico; reintentar u otro documento.

​
Auditoría y listado de verificaciones

Cada solicitud de ID Verification se guarda en id_verification_verifications. La respuesta del POST incluye verificationId cuando se persiste. Todos los endpoints son de la API Gueno; en esta documentación y en las respuestas no se menciona ningún proveedor externo.

​
Obtener una verificación

GET https://api.gu1.ai/api/kyc/id-verification/verifications/:id
Devuelve un registro por ID. Path: id — UUID de la verificación (el verificationId de la respuesta del POST o del listado). Respuesta (200): Mismo formato que un ítem del listado. 404 si no existe o no pertenece a tu organización.

​
Listar verificaciones

GET https://api.gu1.ai/api/kyc/id-verification/verifications?entityId={entityId}&limit=50&offset=0
Query: entityId (opcional), withoutEntity (boolean), status, limit, offset. Respuesta: { "verifications": [ ... ], "pagination": { ... } }.

​
Obtener imágenes del documento almacenadas

Si la verificación tiene imágenes guardadas, podés obtenerlas con: 
GET https://api.gu1.ai/api/kyc/id-verification/verifications/:id/document-front-image
GET https://api.gu1.ai/api/kyc/id-verification/verifications/:id/document-back-image
Path: id — UUID de la verificación. Respuesta: bytes de la imagen. 404 si no existe o no hay imagen almacenada para ese lado.

​
Próximos pasos

Face Match (Documento + Selfie)

Comparar documento y selfie

Crear validación KYC

Verificación por sesión con URL alojada