Verificar Estado de Validación

curl --request GET \
  --url http://api.gu1.ai/api/kyc/validations/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/api/kyc/validations/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/api/kyc/validations/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/api/kyc/validations/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/api/kyc/validations/{id}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "status": "<string>"
}

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>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/api/kyc/validations/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/api/kyc/validations/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/api/kyc/validations/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/api/kyc/validations/{id}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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);
}

validation_id = '550e8400-e29b-41d4-a716-446655440000'

response = requests.get(
    f'https://api.gu1.ai/api/kyc/validations/{validation_id}',
    headers={'Authorization': 'Bearer TU_API_KEY'}
)

validation = response.json()

print('Estado:', validation['status'])
print('Verificado:', validation['status'] == 'approved')

if validation['status'] == 'approved':
    print('Datos verificados:', validation['extractedData'])

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

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:

Clave	Alias array	Campos típicos
`id_verification`	`id_verifications[0]`	`document_type`, `document_number`, `front_image`, `back_image`, `portrait_image`, `warnings`, `matches`
`liveness`	`liveness_checks[0]`	`score`, `method`, `reference_image`, `video_url`, `warnings`, `matches`
`face_match`	`face_matches[0]`	`score`, `source_image`, `target_image`, `warnings`
`aml_screening`	`aml_screenings[0]`	`status`, `warnings`
`ip_analysis`	`ip_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

Usar Webhooks, No Polling

En lugar de verificar repetidamente el estado de validación, usa webhooks para recibir notificaciones en tiempo real.

Cachear Estado de Verificación

Almacena el estado de verificación en tu base de datos y actualízalo vía webhooks. No consultes la API en cada solicitud.

Manejar Verificaciones Expiradas

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

Listar Validaciones KYC de una Entidad Sincronizar Validación KYC

⌘I

​Resumen

​Obtener Validación por ID

​Ejemplo

​Obtener Validación Actual para Entidad

​Obtener Estado KYC de Entidad

​Respuesta

​Valores de Estado

​Objeto decision

​Resultados por feature

​Patrones de Integración Comunes

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

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

​Mejores Prácticas

​Próximos Pasos

Crear Validación KYC

Integración Webhook

Resumen

Obtener Validación por ID

Ejemplo

Obtener Validación Actual para Entidad

Obtener Estado KYC de Entidad

Respuesta

Valores de Estado

Objeto `decision`

Resultados por feature

Patrones de Integración Comunes

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

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

Mejores Prácticas

Próximos Pasos