Demandes KYC

Une demande KYC représente une tentative unique de vérifier l'identité d'une personne (INDIVIDUAL) ou celle d'une entreprise, avec ses administrateurs et ses bénéficiaires effectifs (BUSINESS). Tous les points de terminaison ci-dessous se trouvent sous /api/v1/kyc/requests.

Tous les points de terminaison exigent une clé d'API dotée de la portée pertinente. Voir Authentification.

Créer une demande

POST /api/v1/kyc/requests    Portée : kyc:write

Crée une nouvelle demande à l'état PENDING_UPLOAD. Les données du demandeur sont facultatives : si vous ne les transmettez pas, le demandeur les renseigne via la session hébergée.

Corps de la requête

{
  "type": "INDIVIDUAL",
  "purpose": "Financing an iPhone 16, 24 months",
  "externalRef": "your-id-here",
  "subTenantName": "Acme Corp",
  "subTenantExternalId": "cust_8842",
  "applicant": {
    "externalRef": "your-applicant-id",
    "fullName": "Jane Doe",
    "dateOfBirth": "1990-04-12",
    "nationality": "US",
    "email": "jane@example.com",
    "phone": "+14155551234",
    "emailVerified": false,
    "phoneVerified": false,
    "metadata": { "anyKey": "anyValue" }
  }
}

Raison de la vérification

Chaque demande a une raison : pourquoi vous vérifiez la personne, en quelques mots. L'envoyer est facultatif, mais une raison précise est recommandée, car elle rend la détection de fraude utile. Certivant lit la raison et la rattache à l'une des quelque 110 entrées d'une liste de raisons — par exemple financement d'un téléphone ou d'un appareil, forfait mobile, activation d'une carte SIM, prêt personnel, carte de crédit, location de voiture, crypto-actifs, compte bancaire, location d'un logement, prêt hypothécaire, signature chez le notaire / acte, assurance, emploi ou vérification de l'âge. Chaque raison appartient à une famille : Téléphones et appareils, Lignes mobiles et SIM, Prêts et crédit, Véhicules, Biens de grande valeur, Mouvements d'argent et crypto-actifs, Ouverture de compte, Location d'un logement, Propriété et hypothèque, Autre (aucun argent en jeu) ou Indéterminée.

• Seule la famille est comparée. Le réseau de prévention de la fraude compare la famille entre entreprises — jamais le texte, jamais la raison précise. Le texte lui-même est chiffré, n'est jamais partagé avec une autre entreprise et ne circule qu'en HTTPS.
• Seuls l'argent ou le crédit en jeu comptent. Une demande n'entre dans les modèles de fraude que si de l'argent ou du crédit est en jeu. Une signature chez le notaire, un prêt hypothécaire, une assurance, des services publics, un emploi ou des soins de santé sont enregistrés, mais ne comptent jamais : une personne qui signe un acte chez le notaire, puis finance un téléphone un mois plus tard, n'est pas signalée.
• Les raisons sensibles ne sont jamais partagées. La santé, le droit, l'immigration, les jeux d'argent, les difficultés d'endettement, les rencontres, la religion ou les dons, les décès ou successions et les biens à vente réglementée selon l'âge sont enregistrés comme « Autre ».
• Soyez précis. Une raison comme KYC ou verification ne dit pas ce que la personne achète. Par défaut, la demande est tout de même créée, avec un avertissement. Si votre organisation a activé Refuser les motifs vagues (Paramètres → Prévention de la fraude → Règles du réseau antifraude), elle est plutôt refusée avec un 422.
• N'y mettez aucun renseignement personnel. Les adresses courriel, numéros de téléphone, de carte et de pièce d'identité ainsi que les dates sont retirés avant qu'une IA lise la raison — ne les y inscrivez pas.

La réponse de création indique comment la raison a été lue :

Les mêmes champs sont renvoyés par POST /api/v1/kyc/forms/:formId/send. Pour une vue d'ensemble, voir Réseau antifraude.

La raison est choisie dans cet ordre : le purpose que vous envoyez, puis la raison par défaut du formulaire (à définir dans l'éditeur de formulaires), puis « New customer verification », toujours stockée en anglais avec exactement ce texte. Les intégrations qui n'envoient aucune raison, comme les modules de signature électronique, ne reçoivent donc jamais d'erreur. La raison par défaut n'est jamais refusée (même avec Refuser les motifs vagues), ne produit aucun avertissement et n'implique aucun argent à risque : elle n'alimente donc pas les schémas du réseau antifraude.

Réponse (201)

{
  "id": "req_01J...",
  "status": "PENDING_UPLOAD",
  "type": "INDIVIDUAL",
  "externalRef": "your-id-here",
  "subTenantName": "Acme Corp",
  "subTenantExternalId": "cust_8842",
  "pendingDocTypes": ["GOVERNMENT_ID", "SELFIE"],
  "purposeQuality": "informative",
  "applicant": { ... },
  "createdAt": "2026-05-27T10:00:00.000Z"
}

pendingDocTypes reflète les paramètres KYC de votre organisation : ce qui est exigé dépend notamment de l'activation de la vivacité, d'un justificatif de domicile, etc.

purposeQuality vaut informative, generic ou unusable. Lorsque la raison demande votre attention, un tableau warnings est ajouté avec purpose_too_generic, purpose_unusable et/ou purpose_contains_personal_data.

Erreurs

• 400 VALIDATION_ERROR : le corps n'a pas passé la validation Zod. error.fields liste chaque chemin en échec.
• 403 FORBIDDEN : la clé ne possède pas kyc:write, ou (error.reason = "form_not_allowed") la clé est restreinte à certains formulaires et la demande n'a pas de formId ou en désigne un autre.
• 404 NOT_FOUND : le formId n'est pas un formulaire de votre organisation.
• 409 CONFLICT : votre externalRef est déjà utilisée par une autre demande de cette organisation. Utilisez une autre référence ou interrogez la demande existante.
• 422 : votre organisation refuse les motifs vagues (Refuser les motifs vagues) et purpose est trop générique ou inutilisable. Indiquez ce qui est acheté ou financé. Également renvoyé par POST /api/v1/kyc/forms/:formId/send.

Lister les demandes

GET /api/v1/kyc/requests    Portée : kyc:read

Paramètres de requête

Réponse

{
  "data": [
    { "id": "req_...", "status": "APPROVED", "type": "INDIVIDUAL", "createdAt": "...", "applicant": {...} },
    ...
  ],
  "pagination": {
    "total": 248,
    "page": 1,
    "limit": 20,
    "pages": 13
  }
}

Consulter une demande

GET /api/v1/kyc/requests/:id    Portée : kyc:read

Renvoie la vérification complète : le demandeur, chaque document envoyé (avec les champs extraits par reconnaissance optique de caractères), chaque contrôle automatisé, le détail complet du risque, les signaux de fraude et le journal d'audit. C'est tout ce qu'affiche l'écran de détail du tableau de bord : vous pouvez ainsi créer votre propre interface de révision sans jamais devoir envoyer votre équipe vers Certivant.

Réponse

{
  "id": "req_...",
  "status": "ESCALATED",
  "type": "INDIVIDUAL",
  "externalRef": "user-9281",
  "subTenantName": null,
  "subTenantExternalId": null,
  "reviewedBy": null,
  "reviewNote": null,
  "completedAt": null,
  "createdAt": "2026-05-27T10:00:00.000Z",
  "updatedAt": "2026-05-27T10:03:12.000Z",

  "applicant": {
    "id": "app_...",
    "fullName": "Alex Singh",
    "dateOfBirth": "1988-11-03T00:00:00.000Z",
    "nationality": "GBR",
    "email": "alex@example.com",
    "emailVerified": true,
    "phone": "+447700900100",
    "phoneVerified": false,
    "metadata": {}
  },

  "documents": [
    {
      "id": "doc_...",
      "documentType": "id_card",
      "side": "front",
      "status": "done",
      "mimeType": "image/jpeg",
      "fileSize": 412938,
      "parsedData": {
        "fullName": "Alex Singh",
        "dateOfBirth": "1988-11-03",
        "documentNumber": "D1234567",
        "expiryDate": "2030-01-15",
        "nationality": "GBR",
        "issuingCountry": "GBR",
        "address": "12 High St, London"
      },
      "createdAt": "2026-05-27T10:01:00.000Z"
    }
  ],

  "checks": [
    { "id": "chk_1", "checkType": "ocr",        "provider": "aws_textract", "status": "passed", "score": 0.95, "startedAt": "...", "finishedAt": "..." },
    { "id": "chk_2", "checkType": "face_match", "provider": "azure_face",   "status": "passed", "score": 0.88 },
    { "id": "chk_3", "checkType": "liveness",   "provider": "azure_face",   "status": "passed", "score": 0.92 },
    { "id": "chk_4", "checkType": "sanctions",  "provider": "ofac",         "status": "failed", "score": 0.0 }
  ],

  "riskScore": {
    "overallScore": 62,
    "decision": "escalate",
    "autoDecision": true,
    "factors": [
      { "factor": "document_authenticity", "impact": 1.0, "description": "Barcode + metadata valid" }
    ],
    "rejectionReasons": [],
    "verdictMeta": {
      "factorVerdicts": [
        { "id": "1.1", "section": "Identity Document", "label": "Document authenticity", "weight": 15, "state": "pass", "evidence": ["barcode_valid"] },
        { "id": "4.2", "section": "Screening",         "label": "Sanctions / PEP",       "weight": 20, "state": "fail", "evidence": ["ofac_possible_match"] }
      ],
      "disqualifiers": [],
      "reviewTriggers": ["sanctions_possible_match"],
      "effectiveThresholdApprove": 80
    }
  },

  "fraudSignals": [
    { "signalType": "device_reuse", "severity": "low", "details": { "matchedFingerprint": "..." } }
  ],

  "auditLogs": [
    { "id": "log_1", "actorType": "api",    "actorId": "kyk_prod_ab",  "eventType": "request.created",   "payload": {}, "createdAt": "..." },
    { "id": "log_2", "actorType": "system", "actorId": "orchestrator", "eventType": "request.escalated", "payload": { "reason": "sanctions" }, "createdAt": "..." }
  ]
}

Référence des champs

Erreurs

• 404 NOT_FOUND : aucune demande ne correspond à cet identifiant dans votre organisation. Les demandes appartiennent aux organisations : vous ne pouvez pas lire les données d'une autre organisation, même avec une clé valide.

Afficher une vérification dans votre propre application

La réponse détaillée est conçue pour être affichée directement : un seul appel vous fournit tout ce qu'affiche le tableau de bord, et vos réviseurs n'ont jamais à se connecter à Certivant :

Soumettre au traitement

POST /api/v1/kyc/requests/:id/submit    Portée : kyc:submit

Transmet une demande PENDING_UPLOAD au pipeline de traitement automatisé. Tous les documents requis doivent avoir été envoyés (pendingDocTypes doit être vide) avant de pouvoir soumettre la demande.

Réponse

{
  "id": "req_...",
  "status": "PROCESSING",
  "message": "Request submitted; you will receive a webhook when processing completes."
}

Erreurs

• 400 BAD_REQUEST : pendingDocTypes n'est pas vide. Envoyez d'abord les documents manquants.
• 409 CONFLICT : la demande n'est pas à l'état PENDING_UPLOAD. Vous ne pouvez soumettre qu'une seule fois.

Décision manuelle (demandes escaladées)

POST /api/v1/kyc/requests/:id/decision    Portée : kyc:manage

Remplace une demande ESCALATED par une décision humaine. Ce point de terminaison est destiné aux outils internes : la plupart des décisions sont prises depuis le tableau de bord.

Corps de la requête

{ "decision": "APPROVED", "note": "Confirmed identity against internal CRM record" }

Réponse

{ "id": "req_...", "status": "APPROVED", "decision": "APPROVED", "reviewNote": "..." }

Erreurs

• 409 CONFLICT : la demande n'est pas à l'état ESCALATED. Vous ne pouvez pas remplacer une approbation automatique.

Soumettre à nouveau une demande rejetée

POST /api/v1/kyc/requests/:id/resubmit    Portée : kyc:write

Ramène une demande REJECTED à l'état PENDING_UPLOAD afin que le demandeur puisse réessayer. Les documents précédents sont supprimés ; le demandeur en envoie de nouveaux.

Réponse

{ "id": "req_...", "status": "PENDING_UPLOAD" }

Erreurs

• 409 CONFLICT : la demande n'est pas à l'état REJECTED. Seules les demandes rejetées peuvent être soumises à nouveau ; les demandes annulées ou approuvées ne le peuvent pas.

Supprimer une demande

DELETE /api/v1/kyc/requests/:id    Portée : kyc:write

Supprime définitivement la demande et tout ce qui s'y rattache : la suppression se propage aux documents, contrôles et scores de risque de la demande, retire les images et PDF d'identité envoyés du stockage, et supprime la fiche du demandeur lorsqu'aucune autre demande ne la référence. Utilisez cette opération pour honorer la demande de suppression d'un client ou pour purger une vérification de test.

Réponse

{
  "success": true,
  "documentsDeleted": 3,
  "applicantDeleted": true
}

• documentsDeleted : nombre de fichiers stockés supprimés.
• applicantDeleted : indique si le demandeur a été nettoyé en tant qu'enregistrement orphelin (false s'il a encore d'autres demandes).

Erreurs

• 404 NOT_FOUND : aucune demande ne correspond à cet identifiant dans votre organisation.

Signaler le résultat

POST /api/v1/kyc/requests/:id/outcome    Portée : kyc:write

Facultatif. Indiquez à Certivant si l'achat ou le crédit visé par la vérification a réellement été livré ou annulé. Appelez ce point de terminaison une fois la demande tranchée.

Corps de la requête

{ "fulfilled": true }

Réponse

{ "id": "req_...", "fulfilled": true, "recorded": true }

recorded: false signifie que la demande ne figure pas encore dans le réseau antifraude (par exemple, elle n'a pas de clés d'identité). Rien n'est perdu : vous pouvez renvoyer le résultat plus tard. Vous pouvez aussi rappeler le point de terminaison à tout moment pour modifier la réponse.

Erreurs

• 404 NOT_FOUND : aucune demande avec cet identifiant dans cette organisation.
• 409 CONFLICT : la demande n'est pas encore tranchée. Son statut doit être APPROVED, REJECTED, ESCALATED ou PENDING_SECOND_REVIEW.

Obtenir les signaux de fraude

GET /api/v1/kyc/requests/:id/fraud-signals    Portée : kyc:read

Renvoie les signaux de fraude liés à l'appareil, au réseau et au comportement, collectés pendant la vérification.

Réponse

[
  {
    "signalType": "device_reused",
    "severity": "medium",
    "details": { "previousRequestIds": ["req_..."], "matchedFingerprint": "..." }
  },
  {
    "signalType": "vpn_detected",
    "severity": "low",
    "details": { "asn": 13335, "isp": "Cloudflare" }
  }
]

La gravité vaut low, medium ou high. Les signaux de gravité élevée font automatiquement escalader la demande vers un examen manuel.

Surveillance continue LBC/FT

Une vérification approuvée peut être soumise à un nouveau criblage afin de détecter de nouvelles correspondances de sanctions, de PPE (personnes politiquement exposées) et de médias défavorables (voir Surveillance continue). La surveillance est une fonctionnalité de forfait, facturée par personne surveillée et par année.

POST renvoie 409 pour une vérification qui n'est pas approuvée, 403 lorsque votre forfait n'inclut pas la surveillance, et 402 lorsqu'il n'y a pas de crédit pour une personne au-delà du quota inclus.

Les nouvelles correspondances arrivent sous la forme du webhook kyc.monitoring.alert (voir Événements webhook) : data.monitoring contient alertType (sanctions_match, pep_match, adverse_media, sanctions_unverifiable), severity et, pour une PPE, pepTier (de 1, chefs d'État et ministres, à 4, proches et relations d'affaires) ou adverseMedia: true. data.sanctions.listsChecked nomme les listes criblées ; les fournisseurs de criblage ne sont jamais nommés.

La vérification elle-même porte le même pepTier / adverseMedia sous data.sanctions dans son webhook de décision.

Supprimer un demandeur (effacement RGPD)

DELETE /api/v1/kyc/applicants/:applicantId    Portée : kyc:manage

Supprime définitivement un demandeur ainsi que toutes les demandes qui lui sont liées. C'est le point de terminaison du droit à l'effacement prévu à l'article 17 du RGPD. Le journal d'audit conserve une marque de suppression avec l'horodatage de la suppression, mais aucune donnée personnelle.

Réponse

{ "success": true, "deletedRequestIds": ["req_...", "req_..."] }