Gehostete Sitzungen

Eine gehostete Sitzung ist der einfachste Weg, Dokumente einzusammeln. Sie erstellen die Anfrage serverseitig, fordern bei Certivant eine Sitzungs-URL an und übergeben sie dem Antragsteller. Certivant übernimmt Dokumenten-Upload, Kamera-Erfassung, Lebenderkennung, OCR-Rückmeldung und Wiederholungsversuche — Sie warten lediglich auf den Webhook.

Wann Sie eine Sitzung verwenden

Die meisten Integrationen verwenden Sitzungen. Der Dokumenten-Upload per API ist ein Ausweg für Sonderfälle.

Eine Sitzungs-URL erzeugen

POST /api/v1/kyc/requests/:id/session-url    Berechtigungsbereich: kyc:write

Die Anfrage muss sich im Status PENDING_UPLOAD befinden.

Anfrage-Body

{
  "expiresInHours": 72,
  "redirectUrl": "https://yourapp.example.com/onboarding/complete"
}

Antwort

{
  "sessionUrl": "https://app.certivant.com/s/01HZ7K8Y...",
  "expiresAt": "2026-05-30T10:00:00.000Z"
}

Die URL enthält ein signiertes Token für einmalige Verwendung. Nach Ablauf (oder nachdem der Antragsteller eingereicht hat) wird es ungültig. Erzeugen Sie eine neue URL, wenn der Antragsteller einen weiteren Versuch benötigt.

Der Ablauf für den Antragsteller

graph LR
  A[You email the session URL] --> B[Applicant clicks]
  B --> C[Welcome screen with your branding]
  C --> D[Capture front of ID]
  D --> E[Capture back of ID]
  E --> F[Capture selfie + liveness]
  F --> G[Confirm details extracted from ID]
  G --> H[Submit]
  H --> I[Thank-you page]
  I --> J{redirectUrl set?}
  J -->|yes| K[Redirect to your URL]
  J -->|no| L[Stay on Certivant page]
  H -.->|automatically| M[POST /submit fires]
  M -.->|webhook| N[kyc.request.processing]

Der Antragsteller benötigt kein Konto, um die Sitzungs-URL zu nutzen — Certivant stellt ihm keine Anmeldung aus. Er klickt, schließt den Ablauf ab und geht. Der gesamte Zustand liegt an der Anfrage, nicht an einem Nutzerdatensatz.

Branding und White-Label

Die gehostete Oberfläche übernimmt die White-Label-Einstellungen Ihrer Organisation — Logo, Markenfarbe, Support-E-Mail-Adresse und eine eigene Domain, sofern Sie eine konfiguriert haben. Nehmen Sie diese Einstellungen einmal unter Einstellungen → White-Label im Dashboard vor; jede Sitzung erbt sie.

Eigene Domains

Standardmäßig liegen die URLs der gehosteten Sitzungen und Formulare auf dem gemeinsamen Certivant-Host (app.certivant.com/s/…). Wenn Sie sie auf Ihrer eigenen Domain wünschen (verify.yourcompany.com stattdessen), richten Sie unter Einstellungen → White-Label → Eigene Domain eine eigene Domain ein. Dies verschiebt nur die für Antragsteller sichtbaren Links — der API-Host und Ihr Basispfad /api/v1/kyc bleiben unverändert, und Ihre Organisation wird weiterhin über Ihren API-Schlüssel identifiziert.

Mobil oder Desktop

Die Sitzung passt sich an und funktioniert auf Smartphones, Tablets und Desktops. Die Dokumentenerfassung nutzt auf dem Mobilgerät die Gerätekamera; auf dem Desktop fordert Certivant den Antragsteller per QR-Code auf, zu seinem Telefon zu wechseln, damit Lebenderkennung und Dokumentenscan die bessere Kamera nutzen. Dies geschieht automatisch — Ihre Integration muss nichts erkennen.

Was nach der Einreichung geschieht

Wenn der Antragsteller auf der gehosteten Seite Einreichen klickt:

1. Certivant ruft im Auftrag des Antragstellers intern POST /requests/:id/submit auf.
2. Die Anfrage wechselt in den Status PROCESSING.
3. Der erste Webhook wird ausgelöst: kyc.request.processing.
4. Die Verarbeitung ist abgeschlossen (in der Regel innerhalb von Sekunden). Ein zweiter Webhook wird ausgelöst: kyc.request.approved, kyc.request.rejected oder kyc.request.escalated.
5. Wenn Sie eine redirectUrl übergeben haben, wird der Antragsteller dorthin geleitet. Andernfalls sieht er eine Dankesseite.

Ihr Backend sollte auf den Webhook warten — fragen Sie den Endpunkt der Anfrage nicht ab, um den Abschluss zu erkennen. Siehe Webhooks.

Eine Sitzungs-URL nach einer Ablehnung wiederverwenden

Wird die Anfrage abgelehnt und Sie rufen POST /requests/:id/resubmit auf, wird die bestehende Sitzungs-URL nicht wieder aktiviert. Erzeugen Sie eine neue:

# 1. Reset the rejected request
curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_.../resubmit \
  -H "Authorization: Bearer ck_live_..."

# 2. Generate a fresh session URL
curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_.../session-url \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"expiresInHours": 24}'

Senden Sie die neue URL anschließend per E-Mail an den Antragsteller. Tipp: Verwenden Sie denselben externalRef, damit Ihr Datenbankeintrag weiterhin zugeordnet bleibt.

Formulare als Alternative

Wenn Sie strukturierte Daten erfassen müssen (nicht nur Dokumente) — Antworten auf Compliance-Fragebögen, Angaben zur Herkunft der Mittel, zusätzliche KYB-Felder —, verwenden Sie stattdessen (oder zusätzlich zur Sitzung) Formulare. Formulare liegen im Dashboard unter KYC → Formulare, und jedes Formular hat eine öffentliche Einreichungs-URL: https://app.certivant.com/forms/:slug.

Formulare erzeugen bei der Einreichung automatisch eine KYC-Anfrage, hängen die Antworten des Formulars als Metadaten an und lösen dieselben Webhooks aus. Die Einrichtung ist unter Formulare beschrieben. Entwickler arbeiten mit Formularen in der Regel nicht über die API — vorgesehen ist der Formulareditor im Dashboard.

Fehler

• 400 BAD_REQUEST — die Anfrage befindet sich nicht in PENDING_UPLOAD. Sie können nur für Anfragen, die auf Dokumente warten, Sitzungs-URLs erzeugen.
• 400 VALIDATION_ERROR — expiresInHours liegt außerhalb des Bereichs 1–168, oder redirectUrl ist keine gültige URL.

Sicherheitshinweise

• Die Sitzungs-URL enthält ein signiertes Token — jeder, der die URL kennt, kann die Verifizierung abschließen. Behandeln Sie sie wie einen Link zum Zurücksetzen eines Passworts: Senden Sie sie direkt an den Antragsteller über einen Kanal, auf den nur er Zugriff hat.
• Verwenden Sie für Abläufe mit hohem Risiko kurze Werte bei expiresInHours (24 oder 48). Eine längere Gültigkeit nur dann, wenn der Antragsteller voraussichtlich Zeit braucht, um Dokumente zusammenzutragen.
• Verfällt eine Sitzung ungenutzt, bleibt die zugrunde liegende Anfrage im Status PENDING_UPLOAD. Erzeugen Sie eine neue URL oder bitten Sie den Antragsteller um eine erneute Zusendung.