Verificaciones

Una verificación es una persona pasando por el motor de identidad: documento oficial, prueba de vida y cotejo biométrico. Este es el canal API-direct, el que usas cuando tu backend controla la captura. Si prefieres que Belfort ponga la interfaz, usa el canal embebido.

El flujo son cinco llamadas en orden: crear la sesión, registrar el consentimiento, subir la media, enviarla a evaluar y recoger la evidencia.

El veredicto llega por webhook. GET .../evidence existe para reconciliar, no para hacer polling agresivo.

Los ids de sesión son opacos y con prefijo (vrf_…). Nunca envíes un UUID crudo: la API lo rechaza con 400 INVALID_ID.

Crear una sesión de verificación

POST /v1/verification-sessions

Requiere una API key secreta (belfort_{env}_sk_…) con scope verification:write.

Abre una sesión y devuelve su id (vrf_…). A partir de aquí subes la media y la envías a evaluar. Lleva Idempotency-Key obligatoria: un reintento por timeout devuelve la MISMA sesión, no una segunda.

Parámetros

Idempotency-Key header

Cuerpo de la petición

application/json · schema VerificationSessionCreate

Campo	Requerido	Tipo	Descripción
`applicationId`	no	`string \| null`	Opaque application id.
`callbackUrl`	no	`string (uri) \| null`
`channel`	sí	`api \| sdk \| link \| embed`
`checks`	no	`CheckSelectionInput \| null`
`clientReference`	no	`string \| null`
`country`	no	`string`
`flow`	no	`string \| null`
`flowId`	no	`string \| null`	Opaque flow id.
`locale`	no	`string`
`meta`	no	`object \| null`
`notificationsMode`	no	`belfort_managed \| integrator_managed`
`personId`	no	`string \| null`	Opaque person id.
`policy`	no	`PolicyOverrideInput \| null`
`redirectUrl`	no	`string (uri) \| null`

Respuestas

201 Successful Response — VerificationSessionCreated

Campo	Requerido	Tipo	Descripción
`applicationId`	sí	`string`	Opaque application id.
`callbackSecret`	no	`string \| null`
`channel`	sí	`api \| sdk \| link \| embed`
`clientReference`	sí	`string \| null`
`completedAt`	sí	`string (date-time) \| null`
`country`	sí	`string`
`createdAt`	sí	`string (date-time)`
`currentStep`	sí	`string \| null`
`decidedAt`	sí	`string (date-time) \| null`
`deepLink`	no	`string \| null`
`expiresAt`	sí	`string (date-time) \| null`
`flowId`	sí	`string \| null`	Opaque flow id.
`hostedUrl`	no	`string \| null`
`id`	sí	`string`
`linkToken`	sí	`string \| null`
`locale`	sí	`string`
`personId`	sí	`string \| null`	Opaque person id.
`publicId`	sí	`string`
`requiresApp`	no	`boolean`
`startedAt`	sí	`string (date-time) \| null`
`status`	sí	`pending \| in_progress \| review \| awaiting_input \| approved \| declined \| expired \| abandoned`
`tenantId`	sí	`string`	Opaque tenant id.
`trustScore`	sí	`integer \| null`
`updatedAt`	sí	`string (date-time)`

Errores posibles (problem+json): 400 405 422 500

Registrar el consentimiento

POST /v1/verification-sessions/{session_id}/consent

Requiere una API key secreta (belfort_{env}_sk_…) con scope verification:write.

Deja constancia del consentimiento informado de la persona titular, con su evidencia. Es un requisito de la LFPDPPP y una precondición para evaluar: sin él, submit rechaza.

Parámetros

session_id path · requerido string

Cuerpo de la petición

application/json · schema ConsentRequest

Campo	Requerido	Tipo
`accepted`	sí	`boolean`
`consentedAt`	no	`string (date-time) \| null`
`policyVersion`	no	`string`
`subjectIpAddress`	no	`string \| null`
`subjectUserAgent`	no	`string \| null`

Respuestas

200 Successful Response — ConsentResponse

Campo	Requerido	Tipo
`consentGiven`	sí	`boolean`
`recordedAt`	sí	`string (date-time)`
`status`	sí	`string`

Errores posibles (problem+json): 400 405 422 500

Subir media a la sesión

POST /v1/verification-sessions/{session_id}/media

Requiere una API key secreta (belfort_{env}_sk_…) con scope verification:write.

Envía una captura —anverso o reverso del documento, o el video de prueba de vida— a la sesión abierta. Se llama una vez por pieza.

Parámetros

`session_id` path · requerido	string
`analyze` query	boolean

Respuestas

201 Successful Response — MediaCaptureResult

Campo	Requerido	Tipo	Descripción
`analysis`	no	`CaptureAnalysis \| null`
`kind`	sí	`string`
`mediaId`	sí	`string`	Opaque media asset id.
`mime`	sí	`string`
`sha256`	sí	`string`
`sizeBytes`	sí	`integer`
`status`	sí	`string`

Errores posibles (problem+json): 400 405 422 500

Enviar la sesión a evaluar

POST /v1/verification-sessions/{session_id}/submit

Requiere una API key secreta (belfort_{env}_sk_…) con scope verification:write.

Cierra la captura y dispara el pipeline: consulta a la fuente gubernamental, cotejo biométrico y política de decisión. La respuesta te dice si quedó aprobada, rechazada o en revisión manual; el veredicto definitivo también llega por webhook.

Parámetros

session_id path · requerido string

Respuestas

200 Successful Response

Campo	Requerido	Tipo
`caseId`	no	`string \| null`
`decision`	sí	`DecisionSummary`
`kind`	no	`"pending"`
`status`	sí	`string`
`trackingId`	sí	`string`

Errores posibles (problem+json): 400 405 422 500

Listar sesiones de verificación

GET /v1/verification-sessions

Requiere una API key secreta (belfort_{env}_sk_…) con scope verification:read.

Cursor list de las sesiones del tenant, filtrable por status y applicationId. Devuelve el registro de cada sesión (estado, tiempos, trustScore), no su expediente: para el detalle con pasos del pipeline y biometría pide /report. Requiere scope verification:read.

Parámetros

`status` query
`limit` query	Tamaño de página (1–100).
`startingAfter` query	`nextCursor` de la página anterior. Excluyente con `endingBefore`.
`endingBefore` query	`previousCursor` de la página actual. Excluyente con `startingAfter`.
`includeTotal` query	Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.
`applicationId` query

Respuestas

200 Successful Response — ListEnvelope_VerificationSessionResponse_

Campo	Requerido	Tipo	Descripción
`data`	sí	`VerificationSessionResponse[]`
`hasMore`	sí	`boolean`	`true` si quedan resultados después de esta página.
`limit`	sí	`integer`	El límite realmente aplicado (puede ser menor al pedido).
`nextCursor`	no	`string \| null`	Pásalo como `startingAfter` para la siguiente página.
`object`	no	`"list"`
`previousCursor`	no	`string \| null`	Pásalo como `endingBefore` para la página anterior.
`totalCount`	no	`integer \| null`	Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.

Errores posibles (problem+json): 400 405 422 500

Obtener una sesión de verificación

GET /v1/verification-sessions/{session_id}

Requiere una API key secreta (belfort_{env}_sk_…) con scope verification:read.

El registro de la sesión: estado actual, paso en curso, tiempos, trustScore y las referencias a flow, application y person. Es el estado, no la evidencia — el expediente completo (pasos, biometría, consultas de gobierno) vive en /report, y su copia sellada y archivable en /certificate. Requiere scope verification:read.

Parámetros

session_id path · requerido string

Respuestas

200 Successful Response — VerificationSessionResponse

Campo	Requerido	Tipo	Descripción
`applicationId`	sí	`string`	Opaque application id.
`channel`	sí	`api \| sdk \| link \| embed`
`clientReference`	sí	`string \| null`
`completedAt`	sí	`string (date-time) \| null`
`country`	sí	`string`
`createdAt`	sí	`string (date-time)`
`currentStep`	sí	`string \| null`
`decidedAt`	sí	`string (date-time) \| null`
`expiresAt`	sí	`string (date-time) \| null`
`flowId`	sí	`string \| null`	Opaque flow id.
`id`	sí	`string`
`locale`	sí	`string`
`personId`	sí	`string \| null`	Opaque person id.
`publicId`	sí	`string`
`startedAt`	sí	`string (date-time) \| null`
`status`	sí	`pending \| in_progress \| review \| awaiting_input \| approved \| declined \| expired \| abandoned`
`tenantId`	sí	`string`	Opaque tenant id.
`trustScore`	sí	`integer \| null`
`updatedAt`	sí	`string (date-time)`

Errores posibles (problem+json): 400 405 422 500

Obtener la evidencia de la sesión

GET /v1/verification-sessions/{session_id}/evidence

Requiere una API key secreta (belfort_{env}_sk_…) con scope verification:read.

El paquete de evidencia de la verificación: veredicto, puntuaciones biométricas y referencias a la media, en la forma que exige una constancia NOM-151. Es el canal de lectura por API key — el detalle completo de la sesión vive en el dashboard.

Parámetros

session_id path · requerido string

Respuestas

200 Successful Response — EvidenceBundle

Campo	Requerido	Tipo
`biometric`	no	`BiometricCheckItem[]`
`completedAt`	sí	`string (date-time) \| null`
`consent`	sí	`ConsentRecord \| null`
`createdAt`	sí	`string (date-time)`
`decision`	sí	`DecisionSummary \| null`
`document`	no	`DocumentSummary \| null`
`gov`	no	`app__schemas__verification__GovLookupItem[]`
`media`	sí	`MediaRef[]`
`reuse`	no	`ReuseSummary \| null`
`scores`	sí	`BiometricScores`
`sessionId`	sí	`string`
`trustScore`	sí	`number \| null`
`verificationStatus`	sí	`pending \| in_progress \| review \| awaiting_input \| approved \| declined \| expired \| abandoned`

Errores posibles (problem+json): 400 405 422 500

Obtener el expediente de la sesión

GET /v1/verification-sessions/{session_id}/report

Requiere una API key secreta (belfort_{env}_sk_…) con scope verification:read.

Detalle completo de la verificación: decisión, pasos del pipeline, biometría, documento y consultas de gobierno, con el desglose del trustScore. No expone PII cruda. Es la lectura viva del expediente; si necesitas una copia determinista y sellable, pide /certificate. Requiere scope verification:read.

Parámetros

session_id path · requerido string

Respuestas

200 Successful Response — VerificationReportDetail

Campo	Requerido	Tipo
`biometric`	sí	`BiometricCheckItem[]`
`channel`	sí	`string`
`completedAt`	sí	`string (date-time) \| null`
`createdAt`	sí	`string (date-time)`
`decidedAt`	sí	`string (date-time) \| null`
`decision`	sí	`VerificationReportDecision \| null`
`document`	no	`DocumentSummary \| null`
`gov`	sí	`app__schemas__verification__GovLookupItem[]`
`id`	sí	`string`
`publicId`	sí	`string`
`status`	sí	`string`
`steps`	sí	`VerificationStepItem[]`
`trustBreakdown`	sí	`object \| null`

Errores posibles (problem+json): 400 405 422 500

Obtener la constancia sellada

GET /v1/verification-sessions/{session_id}/certificate

Requiere una API key secreta (belfort_{env}_sk_…) con scope verification:read.

La constancia determinista y archivable de la verificación: el mismo expediente de /report pero sin nada que dependa del instante en que se pide, más contentHash (sha256 del canónico) y signature (HMAC-SHA256). Pedirla dos veces devuelve EXACTAMENTE el mismo documento, byte a byte — sin esa garantía el sello no significaría nada. Requiere scope verification:read.

Parámetros

session_id path · requerido string

Respuestas

200 Successful Response — VerificationCertificate

Campo	Requerido	Tipo
`biometric`	sí	`CertificateBiometric[]`
`contentHash`	sí	`string`
`decidedAt`	sí	`string \| null`
`decidedBy`	sí	`string \| null`
`environment`	sí	`string`
`gov`	sí	`CertificateGov[]`
`media`	sí	`CertificateMedia[]`
`outcome`	sí	`string \| null`
`reasonCodes`	sí	`string[]`
`riskBasis`	sí	`string \| null`
`riskGrade`	sí	`string \| null`
`sessionId`	sí	`string`
`signature`	sí	`string`
`tenantId`	sí	`string`
`trustScore`	sí	`number \| null`
`verificationStatus`	sí	`string \| null`

Errores posibles (problem+json): 400 405 422 500

Seguir el progreso de la sesión (SSE)

GET /v1/verification-sessions/{session_id}/events

Requiere una API key secreta (belfort_{env}_sk_…) con scope verification:read.

Stream Server-Sent Events del avance de los agentes de verificación, para pintar el progreso en vivo. Es el canal del revisor/tenant: se autentica por JWT y valida la pertenencia al tenant. Requiere scope verification:read.

Parámetros

session_id path · requerido string

Respuestas

200 Successful Response

Errores posibles (problem+json): 400 405 422 500