Quickstart.
Tu primera verificación en cinco minutos. Asume que ya tienes una API key — si no, solicita acceso desde el dashboard.
1. Guarda tu key como variable de entorno
TVERIFICAS_API_KEY=tvk_test_xxxxxxxxxxxxx2. Confirma que estás autenticado
curl https://api.empresas.tverificas.com/v1/me \
-H "Authorization: Bearer $TVERIFICAS_API_KEY"Esto devuelve los datos de tu organización y el tipo de key (live o test).
3. Lanza una validación rápida
Para una primera prueba, usa el endpoint sincrónico de validación rápida. Responde en unos segundos y, con una key tvk_test_…, no se factura:
curl https://api.empresas.tverificas.com/v1/identity-validation/1234567890 \
-H "Authorization: Bearer $TVERIFICAS_API_KEY"Respuesta similar a:
{
"id": "9cf1dc24-…",
"endpoint": "identity_validation",
"status": "completed",
"mode": "test",
"cedula_raw": "1234567890",
"sources_total": 1,
"sources_ok": 1,
"duration_ms": 4820,
"response_data": { ... }
}4. Lanza una verificación a fondo
Para correr el endpoint full_check (identidad más unas 40 fuentes colombianas e internacionales: consultas en línea a sitios oficiales y cruces contra bases de datos; lista completa en Fuentes oficiales), usa el POST. Tarda entre 1 y 2 minutos:
curl -X POST https://api.empresas.tverificas.com/v1/searches \
-H "Authorization: Bearer $TVERIFICAS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"cedula": "1234567890",
"endpoint": "full_check",
"purpose": "kyc"
}'5. Modo asíncrono (cargas grandes)
Para cargas que pueden tardar minutos, pasa ?async=true y consulta el estado por separado.
curl -X POST "https://api.empresas.tverificas.com/v1/searches?async=true" \
-H "Authorization: Bearer $TVERIFICAS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"cedula": "1234567890",
"endpoint": "full_check",
"purpose": "kyc"
}'Respuesta inmediata 202 Accepted con el id de la búsqueda en estado pending:
{
"id": "9cf1dc24-193b-4c73-8672-1562daa53d7c",
"status": "pending",
"mode": "live",
"cedula_raw": "1234567890",
"endpoint": "full_check",
"created_at": "2026-04-28T14:08:33Z"
}Consulta el estado cada 1-2 segundos hasta que termine:
curl "https://api.empresas.tverificas.com/v1/searches/9cf1dc24-193b-4c73-8672-1562daa53d7c" \
-H "Authorization: Bearer $TVERIFICAS_API_KEY"El polling termina cuando status es completed, degraded o failed. Patrón completo de polling con código JS en Estado de búsqueda.
6. Próximos pasos
- Lee el detalle de cada endpoint en la sidebar.
- Configura
Idempotency-Keyen producción para no cobrar dos veces por la misma operación. - Ten en cuenta los códigos de error en
/docs/errors.