Sesiones de Verificación

Una sesión representa una verificación de identidad. Al crearla se devuelve una widget_url que usted entrega a su cliente, y un session_id que usa para correlacionar el resultado.

Crear una Sesión

Endpoint: POST /v1/sessions
Autenticación: token Bearer con el scope sessions

curl --request POST \
  --url https://{FQDN}/v1/sessions \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "user_ref": "user-123",
  "language": "es",
  "delivery": { "mode": "webhook" }
}'

{
  "session_id": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "status": "pending",
  "widget_url": "https://{FQDN}/verify/8Kd2mQ…"
}

Campos de la Solicitud

Campos de la Respuesta

Prefill

prefill transporta lo que usted ya sabe sobre la persona. Tiene dos efectos distintos.

{
  "user_ref": "user-123",
  "prefill": {
    "document_type": "drivers_license",
    "issuing_state": "PA",
    "document_number": "31612967",
    "first_name": "Ana",
    "last_name": "Silva",
    "date_of_birth": "1988-03-04"
  }
}

Los campos de prefill distintos de document_type no cambian la decisión a menos que configure data_check: true. Sin él, los valores se transportan para comparación y se reportan en el resultado, pero una discrepancia no enruta la sesión a ninguna parte.

Sin embargo, prefill.document_number sí se valida en esta llamada: un número que viola el formato conocido de su jurisdicción se rechaza con 422 en lugar de aceptarse y fallar después. Verifique un número antes de llegar aquí con el endpoint validador.

Verificaciones de Datos

Configure data_check: true para verificar que el documento pertenece a la persona que usted esperaba — no solo que el documento es genuino.

{
  "user_ref": "user-123",
  "data_check": true,
  "prefill": {
    "first_name": "Ana",
    "last_name": "Silva",
    "date_of_birth": "1988-03-04"
  }
}

Con data_check: true:

• Los datos extraídos se comparan campo por campo contra el payload de prefill.
• El resultado incluye prefill_comparison (resultados por campo, incluidos puntajes de coincidencia difusa de nombres) y prefill_mismatches (los nombres de los campos que discreparon).
• Una discrepancia agrega una verificación blanda fallida, enrutando la sesión a in_review en lugar de rechazarla.

Los nombres se comparan con coincidencia difusa contra un umbral de similitud configurable, de modo que las variaciones ordinarias de ortografía y transliteración no generan falsas discrepancias. data_check: true sin un payload de prefill es un 422 — no habría nada contra qué comparar.

Entrega

{ "delivery": { "mode": "redirect", "redirect_url": "https://you.example/kyc-done" } }

Solicitar el modo webhook sin una webhook_url configurada para su tenant es un 422. Consulte Recepción de Resultados para la verificación de firmas en ambos modos.

Respuestas de Error

Todas estas devuelven 422 con un detail que explica la causa específica:

Las fallas de autenticación y autorización devuelven 401 o 403 — vea Autenticación.

Consultar una Sesión

Endpoint: GET /v1/sessions/{session_id}
Autenticación: token Bearer con el scope sessions

Este es el registro autoritativo de una verificación. Consúltelo cuando necesite una garantía en lugar de un push, para conciliar un webhook que pudo haber perdido, o para leer el resultado de una sesión que fue a revisión manual.

curl --request GET \
  --url https://{FQDN}/v1/sessions/$SESSION_ID \
  --header "Authorization: Bearer $ACCESS_TOKEN"

{
  "session_id": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "user_ref": "user-123",
  "status": "in_review",
  "step": "done",
  "delivery_mode": "webhook",
  "result": { "…": "the normalized result, updated in place" },
  "created_at": "2026-07-31T14:02:11.481Z",
  "updated_at": "2026-07-31T14:04:57.902Z"
}

Las sesiones están estrictamente limitadas al tenant. El session_id de otro tenant devuelve 404 — nunca una divulgación parcial.

Validar un Número de Documento

Endpoint: POST /v1/validators/document-number
Autenticación: no requerida

Una verificación de formato sin estado contra el mismo registro que usa el pipeline de verificación: formatos de licencia de conducir de EE. UU. para los 50 estados y DC, formatos de pasaporte por país, y formatos de cédula de identidad donde la jurisdicción define uno. No se almacena nada y no se consume ninguna verificación. Útil para validar la entrada en su propio formulario antes de crear una sesión.

curl --request POST \
  --url https://{FQDN}/v1/validators/document-number \
  --header 'Content-Type: application/json' \
  --data '{
  "document_type": "drivers_license",
  "number": "31612967",
  "issuing_state": "PA"
}'

{
  "document_type": "drivers_license",
  "number": "31612967",
  "issuing_state": "PA",
  "valid": true,
  "rule": "us_dl:PA",
  "detail": "document number matches the PA license format"
}

valid es deliberadamente de tres valores:

rule identifica qué regla se aplicó — us_dl:PA, passport:USA, passport:generic, o us_dl:unknown_state cuando se envió una licencia sin un estado resoluble (lo que produce valid: null). issuing_state es un código o nombre de estado de EE. UU. para licencias de conducir, y un código de país ISO 3166-1 alpha-3 para pasaportes y cédulas de identidad.

Próximos Pasos

• Entrega del Widget — cómo guiar al cliente a través del flujo
• Recepción de Resultados — manejo de webhooks y redirecciones
• Configuración del Tenant — qué tipos de documento y jurisdicciones acepta