Sesiones de Verificación

Una sesión representa una verificación de identidad. Al crearla se devuelve una widgetUrl que usted entrega a su cliente, y un sessionId 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 '{
  "userRef": "user-123",
  "language": "es",
  "delivery": { "mode": "webhook" }
}'

{
  "sessionId": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "status": "pending",
  "widgetUrl": "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.

{
  "userRef": "user-123",
  "prefill": {
    "documentType": "drivers_license",
    "issuingState": "PA",
    "documentNumber": "31612967",
    "firstName": "Ana",
    "lastName": "Silva",
    "dateOfBirth": "1988-03-04"
  }
}

Los campos de prefill distintos de documentType no cambian la decisión a menos que configure dataCheck: 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.documentNumber 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 dataCheck: true para verificar que el documento pertenece a la persona que usted esperaba — no solo que el documento es genuino.

{
  "userRef": "user-123",
  "dataCheck": true,
  "prefill": {
    "firstName": "Ana",
    "lastName": "Silva",
    "dateOfBirth": "1988-03-04"
  }
}

Con dataCheck: true:

• Los datos extraídos se comparan campo por campo contra el payload de prefill.
• El resultado incluye prefillComparison (resultados por campo, incluidos puntajes de coincidencia difusa de nombres) y prefillMismatches (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. dataCheck: true sin un payload de prefill es un 422 — no habría nada contra qué comparar.

Entrega

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

Solicitar el modo webhook sin una webhookUrl 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/{sessionId}
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"

{
  "sessionId": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "userRef": "user-123",
  "status": "in_review",
  "step": "done",
  "deliveryMode": "webhook",
  "result": { "…": "the normalized result, updated in place" },
  "createdAt": "2026-07-31T14:02:11.481Z",
  "updatedAt": "2026-07-31T14:04:57.902Z"
}

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

Próximos Pasos

• Validador de Número de Documento — verifique un número antes de llegar aquí
• Entrega del Widget — cómo guiar al cliente a través del flujo
• Recepción de Resultados — manejo de webhooks y redirecciones