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…",
  "expiresAt": "2026-08-02T15:02:11.481Z"
}

Campos de la Solicitud

Campos de la Respuesta

Prefill

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

Cada campo de prefill es una cadena de como máximo 255 caracteres. Envíe un campo solo cuando tenga un valor para él: un valor en blanco o solo con espacios se rechaza en lugar de ignorarse, para que un campo que no proporcionó nunca se reporte como uno con el que el documento discrepó.

{
  "userRef": "user-123",
  "prefill": {
    "documentType": "drivers_license",
    "issuingCountry": "USA",
    "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 una regla puede refutar — un dígito verificador que falla, o un valor que ninguna jurisdicción podría emitir — se rechaza con 422 en lugar de aceptarse y fallar después. Un número que simplemente no coincide con ninguna de las formas que mantenemos para su jurisdicción no se rechaza; se transporta, y el resultado publica document_number_valid como undetermined. 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 document_data_match fallida y se reporta en el resultado.

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 errorCode: "validation_error"; errors[] nombra el campo y la causa:

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 sesión de widget. Léalo cuando necesite una garantía en lugar de un push, para recuperar un webhook que pudo haber perdido, o para leer el resultado de una sesión que fue a revisión manual.

Una verificación creada con POST /v1/verifications no se sirve aquí — tiene una lectura propia en GET /v1/verifications/{verificationId}, accesible con el scope verifications. Pasar una de ellas aquí devuelve 404.

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": "completed",
  "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",
  "expiresAt": "2026-08-02T15:02:11.481Z"
}

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

Vencimiento de la Sesión

Una sesión que el cliente no termina a tiempo termina en expired. Su plazo se fija cuando usted la crea: las 48 horas del enlace más la hora que tiene para terminar un cliente que abrió el enlace al final — 49 horas después de la creación por defecto, devuelto como expiresAt en la respuesta de creación y en la lectura. Un cambio posterior en la vigencia del enlace nunca mueve el plazo de una sesión que ya existe.

Todo lo que aún no se envió vence: un enlace que nunca se abrió, o un cliente que se detuvo a mitad de camino. Una sesión vencida no lleva decision ni evaluación, y se le entrega como cualquier otro desenlace — por webhook en modo webhook. Un cliente en un enlace vencido ve el mensaje de enlace vencido en lugar de su redirectUrl, así que en modo redirección le llega como una notificación de resultado cuando tiene un webhookUrl, y por la lectura en cualquier caso. Una vez que una sesión terminó, no se acepta ninguna captura más.

Las verificaciones server-to-server no tienen plazo y nunca vencen.

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
• Sandbox y Datos de Prueba — números de documento reservados que dictan todo el resultado de una verificación