Referencia de la API de Live ID

Tres superficies: gestión de claves (autenticada con sesión del panel, para administradores), el ciclo de vida de la sesión (autenticado con clave y con token de sesión, público) y el webhook. La URL base indicada a continuación es el host de su inquilino.

Emitir una clave de identificación

POST /api/kyc/live-id/:orgSlug/keys    Autenticación: sesión del panel (administrador/propietario)

Emite una clave por perfil. El token en texto plano se devuelve una sola vez: guárdelo de forma segura en su backend; solo se conserva su hash.

Cuerpo de la solicitud

{ "applicantId": "app_…", "label": "mobile-app", "expiresInDays": 365 }

Respuesta 201

{
  "id": "lik_…",
  "token": "livid_…",          // shown ONCE
  "keyVersion": 1,
  "label": "mobile-app",
  "expiresAt": null,
  "createdAt": "2026-06-18T12:00:00.000Z"
}

Endpoints complementarios: GET /api/kyc/live-id/:orgSlug/keys (lista, solo metadatos), DELETE /api/kyc/live-id/:orgSlug/keys/:id (revocar), GET /api/kyc/live-id/:orgSlug/enrollments (lista de perfiles inscritos).

Crear una sesión

POST /api/kyc/public/live-id/sessions    Autenticación: clave de identificación (en el cuerpo)

Llame a este endpoint en el servidor. Verifica la clave, aplica el control de facturación y crea un token de sesión de un solo uso.

Cuerpo de la solicitud

{ "key": "livid_…", "deviceFingerprint": "optional", "captureMethod": "live_camera" }

Respuesta 201

{
  "sessionId": "lis_…",
  "sessionToken": "…",
  "expiresAt": "2026-06-18T12:02:00.000Z",
  "captureUrl": "https://app.certivant.com/live-id/…",
  "nonce": "…"
}

Entregue captureUrl al dispositivo. También se devuelve sessionToken para que pueda consultar el estado desde el servidor. nonce es el valor de un solo uso de la sesión: solo es necesario si construye su propia interfaz de captura (consulte Enviar un selfi).

La creación se rechaza con 429 enrollment_locked mientras el perfil esté bloqueado por validaciones fallidas repetidas (5 fallos en 15 minutos lo bloquean durante 30 minutos y disparan live_id.enrollment.locked).

Abrir la página de captura

GET /live-id/:sessionToken    Autenticación: token de sesión (en la ruta)

La página alojada de captura, pensada para móviles, debe abrirse en el nivel superior: en una ventana emergente, mediante una redirección o en un WebView nativo. Se sirve con frame-ancestors 'none', por lo que no puede incrustarse en un iframe. Muestra la interfaz de cámara y selfi cuando la sesión está activa, y un aviso claro cuando ha caducado, no es válida o ya se completó.

Al cargarse, la página alojada llama a POST /api/kyc/public/live-id/sessions/:sessionToken/open. Eso registra la dirección IP del dispositivo y devuelve el valor de un solo uso de la sesión, que la página envía de vuelta junto con el selfi. A partir de ese momento, un selfi enviado sin el valor correcto se rechaza.

Abrir una captura (solo con interfaz de captura propia)

POST /api/kyc/public/live-id/sessions/:sessionToken/open    Autenticación: token de sesión (en la ruta)

Llame a este endpoint desde el dispositivo cuando se abra su propia pantalla de captura. Respuesta 200:

{ "nonce": "…", "expiresAt": "2026-06-18T12:02:00.000Z" }

Enviar un selfi

POST /api/kyc/public/live-id/validate    Autenticación: token de sesión (en el cuerpo)

La página alojada llama a este endpoint por usted. Documéntelo solo si construye su propia interfaz nativa de captura en lugar de usar la página alojada.

Cuerpo de la solicitud

{ "sessionToken": "…", "selfieImage": "data:image/jpeg;base64,/9j/4AAQ…", "nonce": "…" }

selfieImage acepta una cadena base64 o una URL data:. Mínimo aproximado de 1 KB, máximo de 8 MB.

nonce es el valor de un solo uso de la sesión (de la respuesta de creación o de /open):

• Un valor incorrecto siempre se rechaza (reason: "nonce_mismatch", matched: false).
• Un valor ausente solo se rechaza cuando la captura se abrió con /open (la página alojada siempre lo hace). Las integraciones de servidor a servidor que nunca llaman a /open siguen funcionando sin él, aunque se recomienda enviarlo.

Un mismo selfi nunca puede usarse dos veces: una copia exacta de la foto de referencia inscrita o del selfi de una sesión anterior se rechaza (reason: "replayed_image"). Las copias casi idénticas se informan en los riskSignals del webhook.

Respuesta 200

{
  "matched": true,
  "faceMatchScore": 0.94,
  "livenessScore": 0.98,
  "livePassed": true,
  "reason": "matched",
  "sessionId": "lis_…"
}

reason es uno de matched, face_below_threshold, liveness_failed, face_and_liveness_failed, no_reference_image, nonce_mismatch, replayed_image, near_duplicate_image.

Consultar una sesión

GET /api/kyc/public/live-id/sessions/:sessionToken    Autenticación: token de sesión (en la ruta)

Respuesta 200

{
  "sessionId": "lis_…",
  "status": "completed",
  "matched": true,
  "faceMatchScore": 0.94,
  "livenessScore": 0.98,
  "reason": "matched",
  "expiresAt": "2026-06-18T12:02:00.000Z"
}

status: pending → processing → completed (o expired). Cuando está completed, matched es el veredicto. Consulte cada ~2 s; deténgase al recibir completed o expired.

Webhook: live_id.validation.completed

Se dispara una vez por cada validación completada en la URL de webhook de su inquilino, firmado exactamente igual que cualquier otro webhook de Certivant (X-Certivant-Signature-V2: t=…,v1=…; la cabecera anterior X-KYC-Signature: sha256=… también se sigue enviando).

{
  "event": "live_id.validation.completed",
  "organizationId": "org_…",
  "validationId": "liv_…",
  "sessionId": "lis_…",
  "enrollmentId": "lie_…",
  "applicantId": "app_…",
  "matched": true,
  "faceMatchScore": 0.94,
  "livenessScore": 0.98,
  "decisionReason": "matched",
  "riskSignals": {
    "nearDuplicateImage": false,
    "nearestImageDistance": 0.21,
    "nearestImageSource": "previous_session",
    "nonceVerified": true,
    "deviceIpChanged": false
  },
  "timestamp": "2026-06-18T12:02:00.000Z"
}

Los riskSignals son para su propia decisión de riesgo: nunca cambian matched por sí solos. nonceVerified es verdadero cuando el selfi llevaba el valor de un solo uso de la sesión; deviceIpChanged es verdadero cuando la IP del dispositivo cambió entre /open y el selfi (null cuando no puede compararse).

Webhook: live_id.enrollment.locked

Se dispara cuando un perfil se bloquea tras validaciones fallidas repetidas.

{
  "event": "live_id.enrollment.locked",
  "organizationId": "org_…",
  "enrollmentId": "lie_…",
  "applicantId": "app_…",
  "failures": 5,
  "lockedUntil": "2026-06-18T12:32:00.000Z",
  "timestamp": "2026-06-18T12:02:00.000Z"
}

Consulte Webhooks → Verificación de firma.

Errores