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>",
  "doubleCheckRenaper": true,
  "performDocumentLiveness": true,
  "minimumAge": 123,
  "expirationDateNotDetectedAction": "<string>",
  "invalidMrzAction": "<string>",
  "inconsistentDataAction": "<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

ID Verification es un servicio de verificación de Gu1 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, liveness y captura de documento. Ideal para onboarding y flujos regulados.
  • Face Match (POST /api/kyc/face-match): Comparar dos imágenes (retrato del documento + selfie) para verificar que son la misma persona; devuelve coincidencia + puntuación.
  • ID Verification (POST /api/kyc/id-verification): Enviar frente (y opcional reverso) del documento; obtener validación del documento, datos extraídos (MRZ, nombre, dirección, etc.) y Aprobado/Rechazado. Ideal cuando ya tenés las imágenes del documento y solo necesitás extracción + validación.

​
Prerrequisitos

Antes de usar ID Verification:
  1. Integración ID Verification activada: Tu organización debe tener la integración KYC ID Verification activada (por ejemplo en Marketplace / Integraciones).
  2. Credenciales configuradas: La API key de la integración ID Verification debe estar configurada en la configuración KYC de la organización (lo define el administrador de Gu1). Solo se requiere API key (no webhook secret para este endpoint).
ID Verification 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/id-verification

​
Content-Type

Solo se acepta multipart/form-data. Podés enviar imágenes de dos formas (o combinar):
  1. Como archivos: adjuntar imágenes en los campos del form documentFront y (opcional) documentBack.
  2. Como base64: enviar los mismos nombres de campo con la imagen en base64 (con o sin prefijo data:image/...;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=----...
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

​
documentFront
file | string
required
Imagen del frente del documento. Enviar como archivo (recomendado) o como string (base64, con o sin prefijo data:image/...;base64,). Formatos: JPEG, PNG, WebP, TIFF, PDF. Máx. 5MB.
​
documentBack
file | string
Imagen del reverso (opcional; obligatoria para documentos de dos caras como DNI). Igual que documentFront: archivo o base64.
​
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.
​
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 approved del documento ejecuta chequeo RENAPER de datos (DNI + género + trámite desde OCR vs renaper/data). Requiere credenciales RENAPER. El query prevalece sobre el body.
​
doubleCheckRenaper
boolean
Igual que el query param doubleCheckRenaper.
​
performDocumentLiveness
boolean
Si realizar liveness del documento (detectar pantalla/copia). Por defecto false. Enviar como string "true" o "false" en el form.
​
minimumAge
number
Edad mínima (1–120); por debajo se rechaza. Opcional. Enviar como string en el form.
​
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

​
Respuesta exitosa (200 OK)

CampoTipoDescripción
statusstring"approved" | "declined".
verificationIdstring (opcional)ID del registro de auditoría en id_verification_verifications (soporte y listado).
requestIdstring (opcional)ID interno de la solicitud (soporte).
extractedDataobject (opcional)OCR y metadatos de verificación del servicio ID Verification de Gu1, normalizados y persistidos en auditoría. Ver campos de extractedData más abajo.
warningsstring[] (opcional)Array de códigos de riesgo de la verificación (p. ej. DOCUMENT_EXPIRED, POSSIBLE_DUPLICATED_USER). Usar para mostrar o i18n. Ver Códigos de riesgo en advertencias para todos los valores.
debugProviderResponseobject (opcional)Solo no producción (API Gu1 con NODE_ENV=development). Respuesta completa de verificación sanitizada para depuración (sin imágenes/base64). No usar en integraciones de producción.
doubleCheckRenaperboolean (opcional)true si se solicitó doble chequeo RENAPER.
responseDoubleChecksobject (opcional)Con doubleCheckRenaper=true: renaper con resultado datos/trámite. Ver KYC validations RENAPER.
Si falla RENAPER tras aprobación OCR, status pasa a "declined" y se añaden códigos RENAPER a warnings.

​
Campos de extractedData

Los siguientes campos se devuelven en extractedData y se guardan en id_verification_verifications.extracted_data (listado/detalle de auditoría). Los campos vacíos se omiten. Identidad y documento (habituales):
CampoTipoDescripción
providerStatusstringDetalle del estado de verificación del documento (p. ej. Approved, Declined). El status de nivel superior es approved / declined.
fullName, firstName, lastNamestringNombre según OCR.
firstSurname, secondSurnamestringCuando vienen en campos complementarios (p. ej. algunos documentos LATAM).
documentNumber, personalNumberstringNúmero de documento y número personal/nacional si aplica.
documentTypestringp. ej. Driver's License, DNI.
taxNumberstringIdentificador fiscal si aplica (p. ej. CPF en extracción complementaria).
dateOfBirth, agestring / numberFecha de nacimiento y edad calculada.
expirationDate, dateOfIssue, firstIssueDatestringFechas del documento (ISO YYYY-MM-DD cuando aplica).
nationality, genderstringPaís y género cuando el OCR los devuelve.
placeOfBirth, maritalStatusstringLugar de nacimiento y estado civil si aplica.
address, formattedAddressstringDirección cuando está presente.
issuingState, issuingStateNamestringJurisdicción emisora (p. ej. BRA, Brazil).
Complementarios (anidados; pueden ir vacíos):
CampoTipoDescripción
extraFieldsobjectClaves adicionales del documento no promovidas a campos de primer nivel (p. ej. categoría de licencia, códigos regionales). Punto de extensión para campos futuros del OCR.
warningMetaobjectMetadatos de advertencias: duplicatedSessionId, duplicatedSessionNumber, duplicatedApiService con POSSIBLE_DUPLICATED_USER.
frontImageQualityScore, backImageQualityScoreobjectPuntuaciones de calidad OCR cuando existen.
mrzobjectCampos MRZ parseados si no están vacíos.
parsedAddressobjectDirección estructurada cuando la verificación la devuelve.
barcodesarrayLecturas de códigos de barras si aplica.
Campos promovidos vs. extensión
  • Los identificadores frecuentes (taxNumber, firstSurname, secondSurname, firstIssueDate, etc.) se elevan al mismo nivel que fullName dentro de extractedData cuando el OCR los devuelve.
  • Cualquier otra clave del documento queda en extractedData.extraFields (mismo objeto en POST, listado y detalle de auditoría).
No incluido en respuestas API ni JSON de auditoría
  • URLs temporales de imágenes del flujo de verificación — usar imágenes almacenadas (document-front-image / document-back-image) de lo que subiste a Gu1.
  • Cuerpo crudo completo de la verificación (no expuesto en APIs de producción).
Ejemplo (aprobado): 
{
  "status": "approved",
  "verificationId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "requestId": "req_abc",
  "extractedData": {
    "providerStatus": "Approved",
    "fullName": "Elena Martínez Sánchez",
    "firstName": "Elena",
    "lastName": "Martínez Sánchez",
    "documentNumber": "YZA123456",
    "documentType": "National ID",
    "dateOfBirth": "1985-03-15",
    "expirationDate": "2030-08-21",
    "nationality": "ESP",
    "address": "Calle Mayor 10, 4B, Madrid",
    "issuingState": "ESP",
    "issuingStateName": "Spain",
    "personalNumber": "AAA123456",
    "dateOfIssue": "2020-01-10",
    "gender": "F",
    "parsedAddress": {
      "street": "Calle Mayor",
      "city": "Madrid",
      "country": "ESP",
      "formatted_address": "Calle Mayor 10, 4B, Madrid"
    },
    "frontImageQualityScore": {
      "overall_score": 97.5,
      "focus_score": 100,
      "is_document_fully_visible": true
    },
    "backImageQualityScore": {
      "overall_score": 96.0,
      "focus_score": 99
    }
  },
  "warnings": []
}
Ejemplo (rechazado con advertencias y campos extra LATAM): 
{
  "status": "declined",
  "verificationId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "requestId": "4e2bf9fb-d75b-4b26-9362-e51436cfe1eb",
  "extractedData": {
    "providerStatus": "Declined",
    "fullName": "Breno Henrique Ferreira Silva",
    "firstName": "Breno Henrique",
    "lastName": "Ferreira Silva",
    "firstSurname": "Ferreira",
    "secondSurname": "Silva",
    "documentNumber": "08585626509",
    "personalNumber": "2156732124SSPBA",
    "documentType": "Driver's License",
    "taxNumber": "10584158599",
    "dateOfBirth": "2004-08-29",
    "age": 21,
    "expirationDate": "2025-03-07",
    "dateOfIssue": "2024-03-08",
    "firstIssueDate": "2024-03-08",
    "nationality": "BRA",
    "gender": "U",
    "placeOfBirth": "Barreiras/Ba",
    "maritalStatus": "UNKNOWN",
    "issuingState": "BRA",
    "issuingStateName": "Brazil",
    "warningMeta": {
      "duplicatedSessionId": "a4bfeef8-6d6e-4e9b-8fcb-44950912b2b4",
      "duplicatedSessionNumber": 2834,
      "duplicatedApiService": "ID_VERIFICATION"
    },
    "frontImageQualityScore": {
      "overall_score": 98.2,
      "focus_score": 100,
      "brightness_score": 94,
      "is_document_fully_visible": true
    },
    "formattedAddress": null,
    "extraFields": {
      "license_category": "AB",
      "restrictions": "01"
    },
    "mrz": {
      "line1": "IDBRA085856265<<<<<<<<<<<<<<<",
      "line2": "0408299M2503077BRA<<<<<<<<<<<6",
      "line3": "SILVA<<BRENO<HENRIQUE<FERREIRA"
    },
    "parsedAddress": {},
    "backImageQualityScore": {
      "overall_score": 97.1,
      "focus_score": 100
    },
    "barcodes": []
  },
  "warnings": ["DOCUMENT_EXPIRED", "POSSIBLE_DUPLICATED_USER"]
}

​
Ejemplo de solicitud

const form = new FormData();
form.append('documentFront', documentFrontFile); // File object
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();
console.log('Status:', result.status, 'Data:', result.extractedData);

​
Respuestas de error

Códigos de error habituales:
CódigoHTTPSignificado
NOT_CONFIGURED403Credenciales de ID Verification (API key) no configuradas en la organización.
NOT_ENABLED403Integración ID Verification no activada para esta organización.
INVALID_REQUEST400Content-Type no es multipart/form-data, o falta/inválido el frente del documento (sin archivo ni base64, o formato/tamaño).
FORBIDDEN403No se pudo completar la verificación (p. ej. créditos).
VERIFICATION_FAILED500No se pudo completar la verificación; reintentar u otro documento.

​
Auditoría y listado de verificaciones

Cada solicitud de ID Verification (éxito o fallo) se guarda en id_verification_verifications para auditoría y cumplimiento. La respuesta incluye verificationId (ID del registro de auditoría) cuando la persistencia tiene éxito. Todos los endpoints siguientes son de la API Gu1.

​
Obtener una verificación

GET https://api.gu1.ai/api/kyc/id-verification/verifications/:id
Devuelve un registro de auditoría 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: id, organizationId, entityId, status, requestId, vendorData, errorMessage, warnings, extractedData, createdAt, documentFrontStoragePath, documentBackStoragePath, storageProvider, etc.
404 si no existe o no pertenece a tu organización.

​
Listar registros de auditoría

GET https://api.gu1.ai/api/kyc/id-verification/verifications?entityId={entityId}&limit=50&offset=0
Parámetros de query:
ParámetroTipoDescripción
entityIdstring (UUID)Opcional. Filtrar por entidad persona.
withoutEntitybooleanSi true, solo devuelve verificaciones sin entidad asociada (p. ej. pestaña «ID Verification sin entidad» en KYC).
statusstringOpcional. Filtrar por estado (approved, declined, failed).
limitnumberMáximo de ítems (por defecto 50, máx. 100).
offsetnumberDesplazamiento de paginación.
Respuesta: { "verifications": [ ... ], "pagination": { "limit", "offset", "total" } }. Cada verificación incluye id, entityId, status, requestId, extractedData, warnings, errorMessage, createdAt y rutas de almacenamiento cuando se guardaron imágenes.

​
Obtener imágenes del documento almacenadas

Si la verificación tiene imágenes guardadas (documentFrontStoragePath / documentBackStoragePath), 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 (p. ej. Content-Type: image/jpeg). 404 si la verificación no existe o ese lado no se almacenó.

​
Convivencia con otros flujos KYC

  • Flujo por sesión crea un registro en kyc_validations y usa una URL alojada; la decisión almacenada puede incluir documento, liveness y face match de la sesión en vivo.
  • Face Match compara retrato del documento + selfie y devuelve coincidencia + puntuación; auditoría en face_match_verifications.
  • ID Verification valida el documento (frente/reverso), extrae datos y devuelve Aprobado/Rechazado; auditoría en id_verification_verifications. No crea un registro en kyc_validations. Usalo cuando necesitás solo validación y extracción del documento sin sesión alojada.

​
Próximos pasos

Face Match (Documento + Selfie)

Comparar documento y selfie

Crear validación KYC

Verificación por sesión con URL alojada