Votre première requête

Parcours de bout en bout — créez une demande, envoyez les documents côté serveur, soumettez-la et traitez le webhook.

Le Démarrage rapide utilisait une session hébergée, car c'est le chemin le plus simple. Cette page présente l'alternative : recueillir les documents dans votre propre interface et les envoyer de serveur à serveur. Choisissez cette approche si vous voulez un contrôle total de l'expérience du demandeur, ou si vous disposez déjà des images des documents.

Le cycle de vie

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 --> [*]

Chaque transition d'état émet un webhook. Dans la plupart des intégrations, vous n'avez besoin de réagir qu'aux états PROCESSING, APPROVED, REJECTED et ESCALATED.

Étape 1 — Créer la demande

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
    }
  }'

Réponse (201) :

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

pendingDocTypes indique les documents dont cette vérification a encore besoin. Cette liste se met à jour à chaque envoi : une fois vide, la demande est prête à être soumise.

Étape 2 — Envoyer les documents

Chaque envoi de document est une requête POST distincte en multipart/form-data. Transmettez documentType (et side pour les documents recto verso, comme les permis de conduire) en paramètres de requête, et le fichier dans un champ nommé 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"

Contraintes :

Taille de fichier : 10 Mo maximum par fichier.
Types MIME : image/jpeg, image/png, image/webp, application/pdf.
side est obligatoire pour GOVERNMENT_ID et accepté pour tout document recto verso ; omettez-le pour SELFIE, PROOF_OF_ADDRESS, etc.

Chaque envoi renvoie le statut mis à jour de la demande :

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

Lorsque pendingDocTypes est vide, vous pouvez soumettre la demande.

Étape 3 — Soumettre au traitement

Vérifiez d'abord le courriel et le téléphone. La vérification du courriel et du téléphone fait partie des contrôles. Si votre organisation l'exige (paramètres KYC/B), assurez-vous que chaque canal requis est vérifié avant la soumission : soit en définissant emailVerified / phoneVerified: true lors de la création (comme à l'étape 1, lorsque vous les avez déjà validés vous-même), soit en faisant effectuer au demandeur l'étape de code par courriel ou téléphone dans une session hébergée. Un canal requis non vérifié fait échouer le contrôle de vérification des coordonnées pendant le traitement.

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

Réponse :

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

La demande passe en PROCESSING. Le moteur de risque de Certivant exécute les contrôles d'authenticité des documents, la reconnaissance optique de caractères (OCR), la correspondance faciale (si vous avez envoyé un selfie), la vivacité, le filtrage des sanctions et les règles personnalisées configurées par votre organisation. Cette étape se termine généralement en quelques secondes.

N'interrogez pas l'API pour obtenir le résultat. Configurez un webhook (voir l'étape 4) : c'est ainsi que Certivant vous indique que la demande est terminée. Les interrogations consomment la limite de débit et ajoutent de la latence.

Étape 4 — Recevoir le webhook

Configurez un point de terminaison webhook dans le tableau de bord, à KYC → Paramètres → Webhooks. À chaque transition de la demande, Certivant envoie une requête POST à votre 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 }
  }
}

Vérifiez l'en-tête X-Certivant-Signature-V2 (voir Vérification de la signature), retrouvez la ligne correspondante dans votre base de données grâce à externalRef, puis poursuivez.

Étape 5 — Gérer l'escalade et le rejet

Toutes les demandes ne sont pas approuvées sans difficulté. Deux issues doivent être prévues :

`kyc.request.escalated`

Le moteur automatisé n'était pas assez sûr de lui, généralement parce que le document était de mauvaise qualité, que la correspondance faciale obtenait un score limite, ou qu'une correspondance de sanctions nécessite un examen humain. Un réviseur de votre organisation ouvre la demande dans le tableau de bord et prend une décision. Vous n'avez rien à faire : la décision finale déclenche un autre webhook (kyc.request.approved ou kyc.request.rejected).

Vous pouvez aussi émettre la décision par programme avec la portée 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`

Le demandeur a échoué aux contrôles : document expiré, correspondance de sanctions, échec de la vivacité, etc. Consultez data.factors et data.disqualifiers dans la charge utile du webhook pour en comprendre la raison. Vous pouvez permettre au demandeur de réessayer en soumettant à nouveau la demande :

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

Cette opération ramène la demande à PENDING_UPLOAD et supprime les documents précédents. Le demandeur peut alors renvoyer ses documents (ou utiliser une nouvelle URL de session hébergée), puis vous pouvez soumettre à nouveau.

Pistes pour la suite

Branchez le gestionnaire de webhooks à votre file de tâches en arrière-plan, afin de relancer vos propres traitements en aval en cas d'échec.
Enregistrez les champs data.extracted (nom, date de naissance, numéro de document) dans la fiche de votre utilisateur, pour éviter de les lui redemander.
Ajoutez dans votre propre produit une vue d'administration qui renvoie vers le tableau de bord Certivant pour toute demande que votre équipe doit examiner.

Pour la référence complète des points de terminaison et les cas limites, consultez Demandes KYC.

Votre première requête

On this page