Skip to main content
GET
/
api
/
kyc
/
validations
/
{id}
Verificar Estado de Validación
curl --request GET \
  --url http://api.gu1.ai/api/kyc/validations/{id} \
  --header 'Authorization: Bearer <token>'
{
  "status": "<string>"
}

​
Resumen

Después de que un cliente complete su verificación KYC, puedes consultar los resultados para verificar el estado, datos extraídos y detalles de decisión.
Aunque puedes consultar esta API, recomendamos fuertemente usar webhooks para recibir notificaciones en tiempo real cuando se complete la verificación.

​
Obtener Validación por ID

GET https://api.gu1.ai/api/kyc/validations/{id}

​
Ejemplo

const validationId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://api.gu1.ai/api/kyc/validations/${validationId}`,
  {
    headers: {
      'Authorization': 'Bearer TU_API_KEY'
    }
  }
);

const validation = await response.json();

console.log('Estado:', validation.status);
console.log('Verificado:', validation.status === 'approved');

if (validation.status === 'approved') {
  console.log('Datos verificados:', validation.extractedData);
  console.log('Campos verificados:', validation.verifiedFields);
}

​
Obtener Validación Actual para Entidad

GET https://api.gu1.ai/api/kyc/entities/{entityId}/current

​
Obtener Estado KYC de Entidad

GET https://api.gu1.ai/api/kyc/entities/{entityId}/status

​
Respuesta

{
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "hasKyc": true,
  "isVerified": true,
  "currentValidation": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "approved",
    "metadata": {},
    "verifiedAt": "2025-01-15T11:00:00Z"
  },
  "lastVerifiedAt": "2025-01-15T11:00:00Z",
  "expiresAt": "2026-01-15T11:00:00Z",
  "needsReverification": false
}

​
Valores de Estado

​
status
string
Estado actual de validación:
  • pending - Validación creada, esperando que el cliente inicie
  • in_progress - Cliente está completando activamente la verificación (llenando formulario)
  • in_review - Verificación completada, requiere revisión manual del equipo de compliance
  • approved - Verificación exitosa, identidad confirmada
  • rejected - Verificación fallida, identidad no confirmada
  • expired - Sesión de verificación expiró (típicamente después de 7 días)
  • abandoned - Cliente inició pero no completó la verificación
  • cancelled - Validación cancelada manualmente

​
Objeto decision

Cuando el estado es approved o rejected, el campo decision contiene el resultado completo del flujo KYC. Gu1 siempre persiste y devuelve ambas formas por cada feature: objeto singular (legacy) y array de un elemento (actual). Podés leer id_verification o id_verifications[0]; se mantienen sincronizados. Lo mismo aplica a liveness / liveness_checks, face_match / face_matches, aml_screening / aml_screenings e ip_analysis / ip_analyses. Los campos de media (front_image, reference_image, images.*, etc.) son claves de almacenamiento Gu1 (kyc/...) tras el ingest. Obtenelas vía la API de media de validación. Filas antiguas pueden tener URLs HTTPS de corta duración hasta sincronizar. Ver ejemplos completos (aprobado y rechazado) en Eventos webhook KYC — objeto decision.

​
Resultados por feature

Cada bloque incluye status (Approved, Declined, In Review, etc.), score opcional, warnings y referencias a media:
ClaveAlias arrayCampos típicos
id_verificationid_verifications[0]document_type, document_number, front_image, back_image, portrait_image, warnings, matches
livenessliveness_checks[0]score, method, reference_image, video_url, warnings, matches
face_matchface_matches[0]score, source_image, target_image, warnings
aml_screeningaml_screenings[0]status, warnings
ip_analysisip_analyses[0]ip_address, country, is_vpn, warnings
Gu1 también expone campos normalizados en extractedData, verifiedFields y warnings de nivel superior (códigos de riesgo).

​
Patrones de Integración Comunes

​
Patrón 1: Verificar Antes de Permitir Acción

async function requerirVerificacion(entityId) {
  const status = await fetch(
    `https://api.gu1.ai/api/kyc/entities/${entityId}/status`,
    {
      headers: { 'Authorization': 'Bearer TU_API_KEY' }
    }
  ).then(r => r.json());

  if (!status.isVerified) {
    throw new Error('El cliente debe completar verificación de identidad');
  }

  if (status.needsReverification) {
    throw new Error('La verificación de identidad expiró. Por favor reverifica.');
  }

  return true;
}

​
Patrón 2: Características Condicionales Según Verificación

async function obtenerCaracteristicasCliente(entityId) {
  const status = await obtenerEstadoKyc(entityId);

  return {
    caracteristicasBasicas: true,
    caracteristicasAvanzadas: status.isVerified,
    transaccionesAltoLimite: status.isVerified && !status.needsReverification,
    transferenciasInternacionales: status.isVerified && tieneAprobacionAml(status)
  };
}

​
Mejores Prácticas

En lugar de verificar repetidamente el estado de validación, usa webhooks para recibir notificaciones en tiempo real.
Almacena el estado de verificación en tu base de datos y actualízalo vía webhooks. No consultes la API en cada solicitud.
Las verificaciones pueden expirar después de cierto período (típicamente 1 año). Verifica needsReverification y solicita a los clientes reverificar cuando sea necesario.

​
Próximos Pasos

Crear Validación KYC

Iniciar nueva sesión de verificación

Integración Webhook

Obtener notificaciones en tiempo real