API für wiederverwendete Verifizierungen

Antragsteller, die bereits eine genehmigte Verifizierung abgeschlossen haben — eine für Privatpersonen oder eine für Unternehmen (KYB) — bei einer anderen Certivant-Organisation, können diese mit Ihrer Organisation teilen. Sie erstellen einen Link, der Antragsteller weist nach, dass die Verifizierung ihm gehört, und willigt ein. Anschließend lösen Sie ein Freigabe-Token für eine einzige Verwendung in eine neue, bereits genehmigte Verifizierung Ihrer Organisation ein. Daten und Dokumentdateien werden in Ihre eigenen Datensätze und Ihren eigenen Speicher kopiert.

Die Endpunkte liegen unter /api/v1/kyc/reuse und verwenden einen API-Schlüssel (Authorization: Bearer ck_live_…). Sie benötigen die Funktion des Tarifs Wiederverwendete Verifizierungen sowie die Schalter Wiederverwendete Verifizierungen annehmen (Privatpersonen) und/oder Wiederverwendete Unternehmensverifizierungen annehmen (Unternehmen) in den Einstellungen unter KYC; beide werden getrennt geschaltet, zeitlich begrenzt und getrennt bepreist. Siehe Authentifizierung.

Ablauf

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

Eine Einladung erstellen

POST /api/v1/kyc/reuse/invitations — Berechtigungsbereich kyc:write.

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

Eine Einladung verfolgen

GET /api/v1/kyc/reuse/invitations/:id — Berechtigungsbereich kyc:read. Die Antwort enthält außerdem type (INDIVIDUAL oder BUSINESS). status ist invited, code_sent, verified, consented (ein Token wartet), redeemed, expired oder revoked. Nach der Einlösung ist requestId die neue Verifizierung. Das Freigabe-Token wird hier nie zurückgegeben; es erreicht Sie über die Weiterleitung des Antragstellers.

Ein Freigabe-Token einlösen

POST /api/v1/kyc/reuse/redeem — Berechtigungsbereich 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
}

Regeln:

• Ein Token ist nur einmal verwendbar, läuft nach seiner Gültigkeitsdauer ab und funktioniert nur für die Organisation, die den Link erstellt hat. Jeder andere Aufrufer erhält 404 invalid_token.
• Der Aufruf erstellt eine Verifizierung, die bereits genehmigt ist, mit Kopien der Antragstellerdaten, der ausgelesenen Dokumentfelder und der Dokumentdateien (in Ihrem Speicherort). Behält Ihre Organisation nach einer Entscheidung keine Dokumente, werden keine Dateien kopiert.
• Bei einer Unternehmensfreigabe (type: "BUSINESS" in der Antwort) ist die neue Verifizierung eine BUSINESS-Anfrage, die außerdem den Unternehmensdatensatz und das Ergebnis der Registerabfrage, die Geschäftsführer und wirtschaftlich Berechtigten (ohne die Verknüpfungen zu den eigenen UBO-Verifizierungen der Quelle), die verifizierte Identität des Vertreters und dessen Abgleich mit den Geschäftsführern sowie gegebenenfalls das Vollmachtsdokument enthält. Lesen Sie sie über die üblichen KYB-Endpunkte (GET /v1/kyc/requests/:id/kyb).
• Die neue Verifizierung vermerkt den API-Schlüssel, der sie eingelöst hat. Ist dieser Schlüssel auf Workflows beschränkt, laufen für sie nur diese Workflows (siehe Workflow-Beschränkung).
• Ihre üblichen Webhooks werden ausgelöst: ein Ereignis kyc.request.approved mit data.reason: "reused_verification".
• Schlägt das Kopieren fehl, wird das Token zurückgegeben (bis es abläuft), und es bleibt nichts zurück.

Fehler

Datenresidenz

Beide Organisationen müssen dieselbe Speicherregion, dieselbe Datenbankregion und dieselbe Residenz für die KI-Verarbeitung haben (eine nicht gesetzte Region passt nur zu einer anderen nicht gesetzten). Andernfalls wird die Freigabe mit residency_mismatch abgelehnt — über eine Regionsgrenze hinweg wird nichts kopiert.

Auf einem öffentlichen Formular

Wenn Ihre Organisation wiederverwendete Verifizierungen einer Art annimmt, bietet ein öffentliches KYC-Formular (Privatperson) oder KYB-Formular (Unternehmen) zu Beginn die Option „Bereits bei Certivant verifiziert?“ an. Der Antragsteller weist die Inhaberschaft nach (per E-Mail zugesendeter Code) und willigt genauso ein wie oben. Das Formular wird aus der geteilten Verifizierung vorausgefüllt (er prüft alles und kann es korrigieren; es werden keine Dokumente angefordert), und die Einreichung wird der neuen, bereits genehmigten wiederverwendeten Verifizierung zugeordnet. Kombinierte KYC- und KYB-Formulare, Einladungslinks (?kyc=) und Formulare, die keine Verifizierung sind, bieten diese Option nicht an.

Die eigenen Endpunkte des Formulars (öffentlich, ohne API-Schlüssel) lauten, zur Information für den Fall, dass Sie ein Formular selbst einbetten:

Ein Formular, das durch einen geheimen Schlüssel geschützt ist, muss ihn bei jedem Aufruf als Header X-Form-Key senden. Eine für ein Formular erstellte Freigabe kann nur durch die Einreichung dieses Formulars eingelöst werden — nicht über POST /reuse/redeem (404 invalid_token) — und die neue Verifizierung wird dem Formular zugeordnet.

Abrechnung

Standardmäßig kostenlos. Ein Preis für eine wiederverwendete Verifizierung (Privatpersonen) und ein Preis für eine wiederverwendete Unternehmensverifizierung (Unternehmen) in den Abrechnungspreisen (oder einer Ausnahme pro Kunde) werden der empfangenden Organisation einmal pro eingelöster Freigabe berechnet; der Aufruf ist pro Freigabe idempotent.

Audit

Das Audit-Protokoll der empfangenden Organisation erfasst reuse.invitation_created, reuse.consent_received und reuse.redeemed. Die Quellorganisation erfasst reuse.consent_recorded und reuse.shared. Die Identität der Quellorganisation wird Ihnen nie offengelegt.