tverificas.
DocumentaciónIr al dashboard →
Endpoints

Crear verificación

Lanza una búsqueda contra el endpoint config seleccionado. Sincrónica por default; pásala a async para cargas grandes.

POST/v1/searches

Body

ParámetroTipoDescripción
cedularequeridostringDocumento del sujeto a verificar (max 40 caracteres). Solo dígitos para CC; otros formatos según endpoint.
endpointstringEndpoint config a ejecutar. Default: full_check. Alternativa: identity_validation.
purposestringPropósito de la consulta para tu propia auditoría (kyc, onboarding, contratacion, etc).
consent_referencestringIdentificador opcional del consentimiento del titular en tu sistema.

Cabeceras opcionales

ParámetroTipoDescripción
Idempotency-KeystringSi pasas la misma key dos veces, la segunda llamada no cobra. Útil para reintentos.
X-User-ReferencestringIdentificador del usuario interno que disparó la consulta (auditoría).

Query params

ParámetroTipoDescripción
waitinteger (segundos)Bloquea hasta N segundos esperando que termine. Útil para flujos sync con timeout custom.
asyncbooleanSi es true, devuelve 202 con la búsqueda en estado pending y haces polling.

Ejemplo

curlbash
curl -X POST https://api.tverificas.com/v1/searches \
  -H "Authorization: Bearer $TVERIFICAS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "cedula": "1020487456",
    "endpoint": "full_check",
    "purpose": "kyc",
    "consent_reference": "consent_xyz_123"
  }'

Respuesta (200 / 201)

json
{
  "id": "9cf1dc24-193b-4c73-8672-1562daa53d7c",
  "endpoint": "full_check",
  "status": "completed",
  "mode": "live",
  "cedula_raw": "1020487456",
  "sources_total": 45,
  "sources_ok": 45,
  "response_data": { /* shape depende del endpoint */ },
  "billable": true,
  "billable_reason": "live",
  "cost_units_charged": "1.00",
  "error": "",
  "retries": 0,
  "user_reference": "",
  "consent_reference": "consent_xyz_123",
  "purpose": "kyc",
  "duration_ms": 1840,
  "created_at": "2026-04-28T14:08:33Z",
  "started_at": "2026-04-28T14:08:33Z",
  "completed_at": "2026-04-28T14:08:35Z"
}

Estados posibles

  • pending — encolada, todavía no arrancó.
  • running — ejecutándose.
  • completed — terminó OK.
  • degraded — terminó con algunas fuentes caídas.
  • failed — falló de manera no recuperable. Ver error.

Cómo recuperar el resultado

En modo síncrono (default), la respuesta del POST ya trae el resultado completo. No tienes que hacer nada más — usa response_data directamente.

En modo asíncrono (?async=true) recibes un 202 con la búsqueda en estado pending. Guarda el id y consulta el estado con GET /v1/searches/{id} hasta que el status sea completed, degraded o failed. La respuesta del polling tiene la misma forma que la respuesta síncrona.

Polling del resultadobash
curl https://api.tverificas.com/v1/searches/9cf1dc24-… \
  -H "Authorization: Bearer $TVERIFICAS_API_KEY"

Patrón completo de polling y tiempos recomendados en Estado de búsqueda.