Ihre erste Anfrage

Durchgängige Anleitung — eine Anfrage erstellen, Dokumente serverseitig hochladen, sie einreichen und den Webhook verarbeiten.

Der Schnellstart verwendete eine gehostete Sitzung, weil dies der einfachste Weg ist. Diese Seite beschreibt die Alternative: Dokumente in Ihrer eigenen Oberfläche erfassen und serverseitig hochladen. Wählen Sie diesen Ansatz, wenn Sie die volle Kontrolle über das Erlebnis des Antragstellers haben möchten oder bereits Dokumentbilder vorliegen haben.

Der Lebenszyklus

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

Jeder Statuswechsel löst einen Webhook aus. Bei den meisten Integrationen müssen Sie nur auf PROCESSING, APPROVED, REJECTED und ESCALATED reagieren.

Schritt 1 — Anfrage erstellen

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

Antwort (201):

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

pendingDocTypes zeigt an, welche Dokumente diese Verifizierung noch benötigt. Das Feld aktualisiert sich bei jedem Upload — sobald es leer ist, kann die Anfrage eingereicht werden.

Schritt 2 — Dokumente hochladen

Jeder Dokument-Upload ist ein eigener multipart/form-data-POST. Übergeben Sie documentType (und bei zweiseitigen Dokumenten wie Führerscheinen side) als Query-Parameter, die Datei in einem Feld namens 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"

Einschränkungen:

Dateigröße: höchstens 10 MB pro Datei.
MIME-Typen: image/jpeg, image/png, image/webp, application/pdf.
side ist für GOVERNMENT_ID erforderlich und für jedes Dokument mit zwei Seiten zulässig; lassen Sie es bei SELFIE, PROOF_OF_ADDRESS usw. weg.

Jeder Upload liefert den aktualisierten Status der Anfrage zurück:

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

Wenn pendingDocTypes leer ist, können Sie einreichen.

Schritt 3 — Zur Verarbeitung einreichen

Verifizieren Sie zuerst E-Mail-Adresse und Telefonnummer. Die E-Mail- und Telefonverifizierung gehört zu den Prüfungen. Wenn Ihre Organisation dies verlangt (KYC/B-Einstellungen), stellen Sie sicher, dass jeder erforderliche Kanal verifiziert ist, bevor Sie einreichen — entweder indem Sie beim Erstellen emailVerified / phoneVerified: true setzen (wie in Schritt 1, wenn Sie sie bereits selbst geprüft haben) oder indem der Antragsteller in einer gehosteten Sitzung den Code-Schritt für E-Mail bzw. Telefon abschließt. Ein nicht verifizierter erforderlicher Kanal lässt die Kontaktprüfung bei der Verarbeitung fehlschlagen.

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

Antwort:

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

Die Anfrage wechselt in den Status PROCESSING. Die Risk-Engine von Certivant führt Echtheitsprüfungen der Dokumente, OCR, Gesichtsabgleich (wenn Sie ein Selfie hochgeladen haben), Lebenderkennung, Sanktionsprüfung und alle eigenen Regeln durch, die Ihre Organisation konfiguriert hat. Dies ist in der Regel innerhalb von Sekunden abgeschlossen.

Fragen Sie das Ergebnis nicht ab. Richten Sie einen Webhook ein (siehe Schritt 4) — so teilt Certivant Ihnen mit, dass die Anfrage abgeschlossen ist. Polling verbraucht das Ratenlimit und erhöht die Latenz.

Schritt 4 — Den Webhook empfangen

Konfigurieren Sie im Dashboard unter KYC → Einstellungen → Webhooks einen Webhook-Endpunkt. Bei jedem Statuswechsel der Anfrage sendet Certivant einen POST an Ihre 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 }
  }
}

Prüfen Sie den Header X-Certivant-Signature-V2 (siehe Signaturprüfung), suchen Sie die Zeile über externalRef in Ihrer Datenbank und fahren Sie fort.

Schritt 5 — Eskalation und Ablehnung behandeln

Nicht jede Anfrage wird reibungslos genehmigt. Auf zwei Ergebnisse müssen Sie sich vorbereiten:

`kyc.request.escalated`

Die automatisierte Engine war nicht sicher — meist weil das Dokument von schlechter Qualität war, der Gesichtsabgleich einen Grenzwert knapp erreicht hat oder ein Sanktionstreffer einen menschlichen Blick braucht. Ein Prüfer in Ihrer Organisation öffnet die Anfrage im Dashboard und entscheidet. Sie müssen nichts tun; die endgültige Entscheidung löst einen weiteren Webhook aus (kyc.request.approved oder kyc.request.rejected).

Sie können die Entscheidung auch programmatisch mit dem Berechtigungsbereich kyc:manage treffen:

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`

Der Antragsteller hat die Prüfungen nicht bestanden — abgelaufenes Dokument, Sanktionstreffer, fehlgeschlagene Lebenderkennung usw. Die Gründe finden Sie in data.factors und data.disqualifiers der Webhook-Nutzlast. Sie können den Antragsteller einen erneuten Versuch machen lassen, indem Sie erneut einreichen:

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

Dies setzt die Anfrage auf PENDING_UPLOAD zurück und entfernt die bisherigen Dokumente. Der Antragsteller kann dann erneut hochladen (oder eine neue URL für die gehostete Sitzung verwenden), und Sie können anschließend erneut einreichen.

Was Sie als Nächstes entwickeln können

Hängen Sie den Webhook-Handler an Ihre Hintergrund-Job-Warteschlange, damit Sie Ihre eigenen nachgelagerten Schritte bei einem Fehler wiederholen können.
Speichern Sie die Felder data.extracted an Ihrem Nutzerdatensatz — Name, Geburtsdatum, Dokumentnummer — und fragen Sie den Nutzer nicht erneut danach.
Ergänzen Sie in Ihrem eigenen Produkt eine Administrationsansicht, die für jede Anfrage, die Ihr Team prüfen muss, auf das Certivant-Dashboard verlinkt.

Die vollständige Endpunkt-Referenz und Sonderfälle finden Sie unter KYC-Anfragen.

Ihre erste Anfrage

On this page