Skip to main content
POST
http://api.gu1.ai
/
api
/
kyc
/
validations
Crear Validación KYC
curl --request POST \
  --url http://api.gu1.ai/api/kyc/validations \
  --header 'Authorization: Bearer <token>'
{
  "providerSessionUrl": "<string>",
  "status": "<string>"
}

​
Resumen

Este endpoint crea una nueva sesión de validación KYC para una entidad persona. Después de crear la validación, recibirás una URL de verificación que puedes compartir con tu cliente.

​
Prerrequisitos

Antes de crear una validación KYC:
  1. La entidad persona debe existir: Crea una entidad persona usando la API de Entidades
  2. Integración KYC configurada: Tu organización debe tener habilitada la integración KYC
  3. API key válida: Autentica con tu clave API

​
Solicitud

​
Endpoint

POST https://api.gu1.ai/api/kyc/validations

​
Headers

{
  "Authorization": "Bearer TU_API_KEY",
  "Content-Type": "application/json"
}

​
Parámetros del Body

​
entityId
string
required
El UUID de la entidad persona a verificar
​
workflowId
string
ID de workflow personalizado para verificación (opcional, usa el por defecto si no se proporciona)
​
webhookUrl
string
URL webhook personalizada para esta validación (opcional, usa el de la organización por defecto)
​
metadata
object
Metadata personalizada para adjuntar a esta validación (máx 10KB)

​
Respuesta

​
Respuesta Exitosa (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "org_abc123",
  "sessionId": "session_xyz789",
  "status": "pending",
  "provider": "kyc_provider",
  "providerSessionUrl": "https://verify.example.com/session_xyz789",
  "isCurrent": true,
  "metadata": {
    "customField": "customValue"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

​
Campos de Respuesta

​
providerSessionUrl
string
La URL de verificación para compartir con tu cliente
​
status
string
Estado actual: pending, in_progress, approved, rejected, expired, abandoned

​
Ejemplo de Solicitud

const response = await fetch('https://api.gu1.ai/api/kyc/validations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer TU_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityId: '123e4567-e89b-12d3-a456-426614174000',
    metadata: {
      userId: 'user_12345',
      source: 'mobile_app'
    }
  })
});

const validation = await response.json();
console.log('URL de verificación:', validation.providerSessionUrl);

​
Respuestas de Error

​
Entidad No Encontrada (404)

{
  "error": "ENTITY_NOT_FOUND",
  "message": "Entity not found"
}

​
Tipo de Entidad Inválido (400)

{
  "error": "INVALID_ENTITY_TYPE",
  "message": "KYC validation is only available for person entities"
}

​
KYC No Configurado (400)

{
  "error": "KYC_NOT_CONFIGURED",
  "message": "La integración KYC no está configurada for this organization. Please contact your administrator."
}

​
Próximos Pasos

Después de crear una validación:
  1. Extrae la URL de verificación de providerSessionUrl
  2. Comparte la URL con tu cliente vía email, SMS o en tu app
  3. Configura endpoint webhook para recibir notificaciones de finalización
  4. Monitorea el estado de validación usando el ID de validación

Obtener URL de KYC

Aprende cómo recuperar la URL

Integración Webhook

Configura notificaciones webhook