Su primera solicitud

Recorrido de principio a fin: cree una solicitud, cargue los documentos desde su servidor, envíela y procese el webhook.

El Inicio rápido usó una sesión alojada porque es la vía más sencilla. Esta página describe la alternativa: recopilar los documentos en su propia interfaz y cargarlos de servidor a servidor. Elija este enfoque cuando quiera control total sobre la experiencia del solicitante o cuando ya tenga imágenes de los documentos archivadas.

El ciclo de vida

stateDiagram-v2
  [*] --> PENDING_UPLOAD: POST /requests
  PENDING_UPLOAD --> PENDING_UPLOAD: POST /documents (each upload)
  PENDING_UPLOAD --> PROCESSING: POST /submit
  PROCESSING --> APPROVED: auto-decision: approve
  PROCESSING --> REJECTED: auto-decision: reject
  PROCESSING --> ESCALATED: auto-decision: escalate
  ESCALATED --> APPROVED: POST /decision (human)
  ESCALATED --> REJECTED: POST /decision (human)
  REJECTED --> PENDING_UPLOAD: POST /resubmit
  APPROVED --> [*]

Cada transición de estado emite un webhook. En la mayoría de las integraciones solo necesita actuar ante PROCESSING, APPROVED, REJECTED y ESCALATED.

Paso 1: crear la solicitud

curl -X POST https://app.certivant.com/api/v1/kyc/requests \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "externalRef": "user-9281",
    "applicant": {
      "fullName": "Alex Singh",
      "dateOfBirth": "1988-11-03",
      "nationality": "GB",
      "email": "alex@example.com",
      "phone": "+447700900100",
      "emailVerified": true,
      "phoneVerified": false
    }
  }'

Respuesta (201):

{
  "id": "req_01J0...",
  "status": "PENDING_UPLOAD",
  "pendingDocTypes": ["GOVERNMENT_ID", "SELFIE"],
  "applicant": { "fullName": "Alex Singh", ... },
  "createdAt": "..."
}

pendingDocTypes indica qué documentos necesita todavía esta verificación. Se actualiza a medida que sube archivos: cuando queda vacío, la solicitud está lista para enviarse.

Paso 2: cargar los documentos

Cada carga de documento es un POST multipart/form-data independiente. Pase documentType (y side para documentos de dos caras, como los permisos de conducir) como parámetros de consulta, y el archivo en un campo llamado file.

# Front of an ID card
curl -X POST "https://app.certivant.com/api/v1/kyc/requests/req_01J0.../documents?documentType=GOVERNMENT_ID&side=front" \
  -H "Authorization: Bearer ck_live_..." \
  -F "file=@/path/to/id-front.jpg"

# Back of the same ID card
curl -X POST "https://app.certivant.com/api/v1/kyc/requests/req_01J0.../documents?documentType=GOVERNMENT_ID&side=back" \
  -H "Authorization: Bearer ck_live_..." \
  -F "file=@/path/to/id-back.jpg"

# Selfie
curl -X POST "https://app.certivant.com/api/v1/kyc/requests/req_01J0.../documents?documentType=SELFIE" \
  -H "Authorization: Bearer ck_live_..." \
  -F "file=@/path/to/selfie.jpg"

Restricciones:

Tamaño de archivo: 10 MB como máximo por archivo.
Tipos MIME: image/jpeg, image/png, image/webp, application/pdf.
side es obligatorio para GOVERNMENT_ID y se acepta para cualquier documento que tenga dos caras; omítalo para SELFIE, PROOF_OF_ADDRESS, etc.

Cada carga devuelve el estado actualizado de la solicitud:

{
  "id": "doc_01J1...",
  "documentType": "GOVERNMENT_ID",
  "side": "front",
  "status": "pending",
  "requestStatus": "PENDING_UPLOAD",
  "pendingDocTypes": ["SELFIE"],
  "fileSize": 412938,
  "mimeType": "image/jpeg"
}

Cuando pendingDocTypes esté vacío, podrá enviar la solicitud.

Paso 3: enviar para su procesamiento

Verifique primero el correo electrónico y el teléfono. La verificación de correo electrónico y teléfono forma parte de las comprobaciones. Si su organización lo exige (Configuración de KYC/B), asegúrese de que cada canal requerido esté verificado antes de enviar: ya sea estableciendo emailVerified / phoneVerified: true al crear la solicitud (como en el paso 1, cuando usted mismo ya los ha validado), o haciendo que el solicitante complete el paso del código de correo electrónico o teléfono en una sesión alojada. Un canal requerido sin verificar hace que falle la comprobación de verificación de contacto durante el procesamiento.

curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_01J0.../submit \
  -H "Authorization: Bearer ck_live_..."

Respuesta:

{ "id": "req_01J0...", "status": "PROCESSING", "message": "..." }

La solicitud pasa a PROCESSING. El motor de riesgo de Certivant ejecuta las comprobaciones de autenticidad del documento, OCR, comparación facial (si subió un selfi), prueba de vida, cribado de sanciones y cualquier regla personalizada que haya configurado su organización. Normalmente termina en cuestión de segundos.

No consulte periódicamente el resultado. Configure un webhook (consulte el paso 4): así es como Certivant le informa de que la solicitud ha terminado. Las consultas periódicas consumen el límite de solicitudes y añaden latencia.

Paso 4: reciba el webhook

Configure un endpoint de webhook en KYC → Configuración → Webhooks en el panel. Cada vez que la solicitud cambie de estado, Certivant enviará una solicitud POST a su URL:

{
  "event": "kyc.request.approved",
  "requestId": "req_01J0...",
  "organizationId": "org_01H...",
  "externalRef": "user-9281",
  "status": "APPROVED",
  "timestamp": "2026-05-27T10:04:21.000Z",
  "data": {
    "score": 94,
    "decision": "approve",
    "extracted": {
      "fullName": "Alex Singh",
      "dateOfBirth": "1988-11-03",
      "documentNumber": "GBR-1234567"
    },
    "liveness": { "isLive": true, "confidence": 0.98 },
    "faceMatch": { "isMatch": true, "confidence": 0.91 }
  }
}

Verifique la cabecera X-Certivant-Signature-V2 (consulte Verificación de firma), busque el registro en su base de datos por externalRef y continúe.

Paso 5: gestione escalados y rechazos

No todas las solicitudes se aprueban sin incidencias. Los dos resultados que debe prever son:

`kyc.request.escalated`

El motor automatizado no tuvo suficiente confianza, normalmente porque el documento era de baja calidad, la comparación facial dio un resultado limítrofe o un resultado de sanciones necesita revisión humana. Un revisor de su organización abre la solicitud en el panel y decide. Usted no tiene que hacer nada; la decisión final dispara otro webhook (kyc.request.approved o kyc.request.rejected).

Sí puede emitir la decisión de forma programática con el ámbito kyc:manage:

curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_01J0.../decision \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "decision": "APPROVED", "note": "Confirmed against internal CRM record" }'

`kyc.request.rejected`

El solicitante no superó las comprobaciones: documento caducado, coincidencia en sanciones, prueba de vida fallida, etc. Revise data.factors y data.disqualifiers en la carga útil del webhook para ver el motivo. Puede permitir que el solicitante lo intente de nuevo reenviando la solicitud:

curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_01J0.../resubmit \
  -H "Authorization: Bearer ck_live_..."

Esto restablece la solicitud a PENDING_UPLOAD y borra los documentos anteriores. Después, el solicitante puede volver a cargar los documentos (o usar una nueva URL de sesión alojada) y usted puede enviarla de nuevo.

Qué construir a continuación

Conecte el manejador de webhooks a su cola de trabajos en segundo plano para reintentar su propio trabajo posterior si falla.
Guarde los campos data.extracted (nombre, fecha de nacimiento, número de documento) en el registro de su usuario, y evite volver a pedírselos.
Añada en su propio producto una vista de administración que enlace con el panel de Certivant para cualquier solicitud que su equipo necesite revisar.

Para la referencia completa de endpoints y casos límite, consulte Solicitudes KYC.

Su primera solicitud

On this page