API des vérifications réutilisées

Les demandeurs qui ont déjà effectué une vérification approuvée — individuelle, ou d'entreprise (KYB) — auprès d'une autre organisation Certivant peuvent la partager avec la vôtre. Vous créez un lien, le demandeur prouve qu'il en est le titulaire et consent au partage, puis vous échangez un jeton de partage à usage unique contre une nouvelle vérification déjà approuvée de votre organisation. Les données et les fichiers de documents sont copiés dans vos propres dossiers et votre propre stockage.

Les points de terminaison se trouvent sous /api/v1/kyc/reuse et utilisent une clé d'API (Authorization: Bearer ck_live_…). Vous devez disposer de la fonctionnalité de forfait Vérifications réutilisées, et avoir activé Accepter les vérifications réutilisées (particuliers) et/ou Accepter les vérifications d'entreprise réutilisées (entreprises) dans Paramètres → KYC ; les deux options s'activent, vieillissent et se tarifent séparément. Voir Authentification.

Déroulement

sequenceDiagram
  participant You as Your system
  participant C as Certivant
  participant A as Applicant
  You->>C: POST /reuse/invitations
  C-->>You: inviteUrl
  You->>A: send inviteUrl
  A->>C: verification ID + emailed code
  A->>C: consent ("Share my verified identity with you")
  C-->>A: redirect to redirectUrl?certivant_share=krs_…
  A->>You: lands on your page with the token
  You->>C: POST /reuse/redeem { shareToken }
  C-->>You: new approved verification

Créer une invitation

POST /api/v1/kyc/reuse/invitations — portée kyc:write.

{
  "id": "clx…",
  "inviteUrl": "https://app.certivant.com/reuse/kri_…",
  "inviteExpiresAt": "2026-10-24T13:00:00.000Z",
  "shareTtlMinutes": 30
}

Suivre une invitation

GET /api/v1/kyc/reuse/invitations/:id — portée kyc:read. La réponse contient aussi type (INDIVIDUAL ou BUSINESS). status vaut invited, code_sent, verified, consented (un jeton est en attente), redeemed, expired ou revoked. Une fois échangée, requestId correspond à la nouvelle vérification. Le jeton de partage n'est jamais renvoyé ici : il vous parvient par la redirection du demandeur.

Utiliser un jeton de partage

POST /api/v1/kyc/reuse/redeem — portée kyc:write.

{ "shareToken": "krs_…" }

{
  "requestId": "clx…",
  "applicantId": "clx…",
  "status": "APPROVED",
  "type": "INDIVIDUAL",
  "externalRef": "crm-7",
  "reused": true,
  "verifiedAt": "2026-09-30T15:12:00.000Z",
  "sourceAgeDays": 24,
  "documentsCopied": 2,
  "chargedCents": 0
}

Règles :

• Un jeton est à usage unique, expire à la fin de sa durée de vie, et ne fonctionne que pour l'organisation qui a créé le lien. Tout autre appelant reçoit 404 invalid_token.
• L'appel crée une vérification déjà approuvée, avec des copies des données du demandeur, des champs de documents extraits et des fichiers de documents (dans votre emplacement de stockage). Si votre organisation ne conserve aucun document après une décision, aucun fichier n'est copié.
• Pour un partage d'entreprise (type: "BUSINESS" dans la réponse), la nouvelle vérification est une demande BUSINESS qui contient aussi la fiche de l'entreprise et le résultat du registre, les administrateurs et les bénéficiaires effectifs (sans les liens vers les vérifications UBO propres à la source), l'identité vérifiée du représentant et sa correspondance avec les administrateurs, ainsi que le document d'autorisation s'il existe. Consultez-la avec les points de terminaison KYB habituels (GET /v1/kyc/requests/:id/kyb).
• La nouvelle vérification enregistre la clé d'API qui l'a échangée. Si cette clé est restreinte à certains workflows, seuls ces workflows s'exécutent pour elle (voir Restriction par workflow).
• Vos webhooks habituels sont déclenchés : un événement kyc.request.approved avec data.reason: "reused_verification".
• Si une copie échoue, le jeton est restitué (jusqu'à son expiration) et rien n'est laissé en suspens.

Erreurs

Résidence des données

Les deux organisations doivent avoir la même région de stockage, la même région de base de données et la même résidence pour le traitement par IA (une région non définie ne correspond qu'à une autre région non définie). Sinon, le partage est refusé avec residency_mismatch : aucune donnée n'est copiée au-delà d'une frontière régionale.

Sur un formulaire public

Lorsque votre organisation accepte les vérifications réutilisées d'un type donné, un formulaire KYC public (particulier) ou un formulaire KYB (entreprise) propose « Déjà vérifié avec Certivant ? » au début. Le demandeur prouve qu'il en est le titulaire (code envoyé par courriel) et consent exactement comme ci-dessus ; le formulaire est pré-rempli à partir de la vérification partagée (il peut tout relire et corriger ; aucun document n'est demandé), et la soumission est rattachée à la nouvelle vérification réutilisée déjà approuvée. Les formulaires combinés KYC + KYB, les liens d'invitation (?kyc=) et les formulaires qui ne sont pas des formulaires de vérification n'offrent pas cette option.

Les points de terminaison propres au formulaire (publics, sans clé d'API) sont, à titre de référence lorsque vous intégrez vous-même un formulaire :

Un formulaire protégé par une clé secrète doit l'envoyer dans l'en-tête X-Form-Key à chaque appel. Un partage créé pour un formulaire ne peut être échangé que par la soumission de ce formulaire — pas avec POST /reuse/redeem (404 invalid_token) — et la nouvelle vérification est attribuée au formulaire.

Facturation

Gratuit par défaut. Un prix de vérification réutilisée (particuliers) et un prix de vérification d'entreprise réutilisée (entreprises), définis dans les prix de facturation (ou dans une exception par client), sont facturés à l'organisation destinataire une fois par partage échangé ; l'appel est idempotent par partage.

Audit

Le journal d'audit de l'organisation destinataire enregistre reuse.invitation_created, reuse.consent_received et reuse.redeemed. L'organisation source enregistre reuse.consent_recorded et reuse.shared. L'identité de l'organisation source ne vous est jamais révélée.