KYC-Anfragen

Eine KYC-Anfrage steht für einen einzelnen Versuch, die Identität einer Person (INDIVIDUAL) oder die Identität eines Unternehmens samt seiner Geschäftsführer und wirtschaftlich Berechtigten (BUSINESS) zu verifizieren. Alle folgenden Endpunkte liegen unter /api/v1/kyc/requests.

Alle Endpunkte benötigen einen API-Schlüssel mit dem jeweiligen Berechtigungsbereich. Siehe Authentifizierung.

Eine Anfrage erstellen

POST /api/v1/kyc/requests    Berechtigungsbereich: kyc:write

Erstellt eine neue Anfrage im Status PENDING_UPLOAD. Die Antragstellerdaten sind optional — wenn Sie sie nicht übergeben, ergänzt der Antragsteller sie über die gehostete Sitzung.

Anfrage-Body

{
  "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" }
  }
}

Grund der Verifizierung

Jede Anfrage hat einen Grund: warum Sie die Person verifizieren, in wenigen Worten. Ihn zu senden ist optional, ein konkreter Grund wird aber empfohlen, weil er die Betrugsprüfung nützlich macht. Certivant liest den Grund und ordnet ihn einem von rund 110 Einträgen einer Grundliste zu — zum Beispiel Finanzierung eines Telefons oder Geräts, Mobilfunktarif, SIM-Aktivierung, Privatkredit, Kreditkarte, Autovermietung, Kryptowährungen, Bankkonto, Wohnungsmiete, Hypothek, Notartermin / Beurkundung, Versicherung, Beschäftigung oder Altersverifizierung. Jeder Grund gehört zu einer Familie: Telefone und Geräte, Mobilfunkanschlüsse und SIM, Darlehen und Kredit, Fahrzeuge, Wertgegenstände, Geldbewegungen und Kryptowährungen, Kontoeröffnung, Wohnungsmiete, Immobilien und Hypothek, Sonstiges (kein Geld im Spiel) oder Unklar.

• Nur die Familie wird verglichen. Das Betrugspräventionsnetzwerk vergleicht zwischen Unternehmen nur die Familie — nie den Text, nie den konkreten Grund. Der Text selbst wird verschlüsselt gespeichert, nie mit einem anderen Unternehmen geteilt und nur über HTTPS übertragen.
• Es zählt nur, wo Geld oder Kredit auf dem Spiel steht. Eine Anfrage fließt nur dann in Betrugsmuster ein, wenn Geld oder Kredit im Spiel ist. Ein Notartermin, eine Hypothek, eine Versicherung, Versorgungsverträge, eine Anstellung oder eine Gesundheitsleistung werden gespeichert, zählen aber nie: Wer beim Notar eine Urkunde unterzeichnet und einen Monat später ein Telefon finanziert, wird nicht markiert.
• Sensible Gründe werden nie geteilt. Gesundheit, Recht, Einwanderung, Glücksspiel, Schuldenprobleme, Dating, Religion oder Spenden, Todesfall oder Nachlass sowie altersbeschränkte Waren werden als „Sonstiges“ gespeichert.
• Seien Sie konkret. Ein Grund wie KYC oder verification sagt nicht, was die Person kauft. Standardmäßig wird die Anfrage trotzdem angelegt — mit einer Warnung. Hat Ihre Organisation Vage Gründe ablehnen aktiviert (Einstellungen → Betrugsprävention → Regeln des Betrugsnetzwerks), wird sie stattdessen mit 422 abgelehnt.
• Lassen Sie persönliche Angaben weg. E-Mail-Adressen, Telefon-, Karten- und Ausweisnummern sowie Datumsangaben werden entfernt, bevor eine KI den Grund liest — tragen Sie sie gar nicht erst ein.

Die Antwort beim Anlegen zeigt, wie der Grund gelesen wurde:

Dieselben Felder liefert auch POST /api/v1/kyc/forms/:formId/send. Einen Gesamtüberblick finden Sie unter Betrugsnetzwerk.

Der Grund wird in dieser Reihenfolge gewählt: der purpose, den Sie senden, dann der Standardgrund des Formulars (im Formulareditor festlegen), dann „New customer verification“, immer auf Englisch und genau mit diesem Text gespeichert. Integrationen, die keinen Grund senden, etwa E-Signatur-Plugins, erhalten daher nie einen Fehler. Der Standardgrund wird nie abgelehnt (auch nicht mit Vage Gründe ablehnen), löst keine Warnung aus und birgt kein Geld im Risiko; er speist daher nicht die Muster des Betrugsnetzwerks.

Antwort (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 richtet sich nach den KYC-Einstellungen Ihrer Organisation — was erforderlich ist, hängt davon ab, ob Sie Lebenderkennung, Adressnachweis usw. aktiviert haben.

purposeQuality ist informative, generic oder unusable. Erfordert der Grund Ihre Aufmerksamkeit, wird ein Array warnings mit purpose_too_generic, purpose_unusable und/oder purpose_contains_personal_data ergänzt.

Fehler

• 400 VALIDATION_ERROR — der Body hat die Zod-Validierung nicht bestanden. error.fields listet jeden fehlerhaften Pfad auf.
• 403 FORBIDDEN — dem Schlüssel fehlt kyc:write, oder (error.reason = "form_not_allowed") der Schlüssel ist auf bestimmte Formulare beschränkt und die Anfrage enthält keine formId oder nennt ein anderes Formular.
• 404 NOT_FOUND — die formId ist kein Formular Ihrer Organisation.
• 409 CONFLICT — Ihre externalRef wird bereits von einer anderen Anfrage dieser Organisation verwendet. Verwenden Sie einen anderen Referenzwert oder fragen Sie die bestehende Anfrage ab.
• 422 — Ihre Organisation lehnt vage Gründe ab (Vage Gründe ablehnen), und purpose ist zu allgemein oder unbrauchbar. Geben Sie an, was gekauft oder finanziert wird. Wird auch von POST /api/v1/kyc/forms/:formId/send zurückgegeben.

Anfragen auflisten

GET /api/v1/kyc/requests    Berechtigungsbereich: kyc:read

Abfrageparameter

Antwort

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

Eine einzelne Anfrage abrufen

GET /api/v1/kyc/requests/:id    Berechtigungsbereich: kyc:read

Liefert die vollständige Verifizierung zurück — den Antragsteller, jedes hochgeladene Dokument (mit den per OCR ausgelesenen Feldern), jede automatisierte Prüfung, die vollständige Aufschlüsselung des Risikos, Betrugssignale und das Audit-Protokoll. Das ist alles, was die Detailansicht des Dashboards anzeigt, sodass Sie Ihre eigene Prüfoberfläche bauen können, ohne Mitarbeiter zu Certivant zu schicken.

Antwort

{
  "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": "..." }
  ]
}

Feldreferenz

Fehler

• 404 NOT_FOUND — keine Anfrage mit dieser ID in dieser Organisation. Anfragen gehören Organisationen; Sie können die Daten einer anderen Organisation nicht lesen, selbst mit einem gültigen Schlüssel.

Eine Verifizierung in Ihrer eigenen App anzeigen

Die Detailantwort ist dafür gedacht, direkt dargestellt zu werden — ein Aufruf liefert alles, was das Dashboard anzeigt, sodass Ihre Prüfer sich nie bei Certivant anmelden müssen:

Zur Verarbeitung einreichen

POST /api/v1/kyc/requests/:id/submit    Berechtigungsbereich: kyc:submit

Gibt eine Anfrage im Status PENDING_UPLOAD in die automatisierte Verarbeitungspipeline frei. Alle erforderlichen Dokumente müssen hochgeladen sein (pendingDocTypes ist leer), bevor Sie einreichen können.

Antwort

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

Fehler

• 400 BAD_REQUEST — pendingDocTypes ist nicht leer. Laden Sie zuerst die fehlenden Dokumente hoch.
• 409 CONFLICT — die Anfrage befindet sich nicht in PENDING_UPLOAD. Sie können nur einmal einreichen.

Manuelle Entscheidung (eskalierte Anfragen)

POST /api/v1/kyc/requests/:id/decision    Berechtigungsbereich: kyc:manage

Überschreibt eine ESCALATED-Anfrage mit einer menschlichen Entscheidung. Dieser Endpunkt ist für interne Werkzeuge gedacht — die meisten Entscheidungen werden über das Dashboard getroffen.

Anfrage-Body

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

Antwort

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

Fehler

• 409 CONFLICT — die Anfrage befindet sich nicht im Status ESCALATED. Eine automatische Genehmigung können Sie nicht überschreiben.

Eine abgelehnte Anfrage erneut einreichen

POST /api/v1/kyc/requests/:id/resubmit    Berechtigungsbereich: kyc:write

Setzt eine REJECTED-Anfrage auf PENDING_UPLOAD zurück, damit der Antragsteller es erneut versuchen kann. Bisherige Dokumente werden entfernt; der Antragsteller lädt neue hoch.

Antwort

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

Fehler

• 409 CONFLICT — die Anfrage befindet sich nicht im Status REJECTED. Nur abgelehnte Anfragen können erneut eingereicht werden; stornierte oder genehmigte nicht.

Eine Anfrage löschen

DELETE /api/v1/kyc/requests/:id    Berechtigungsbereich: kyc:write

Löscht die Anfrage und alles, was daran hängt, dauerhaft: Die Löschung wirkt sich auf die Dokumente, Prüfungen und Risiko-Scores der Anfrage aus, entfernt die hochgeladenen Ausweisbilder bzw. PDFs aus dem Speicher und entfernt den Antragstellerdatensatz, sofern keine andere Anfrage darauf verweist. Verwenden Sie dies, um ein Löschverlangen eines Kunden zu erfüllen oder eine Test-Verifizierung zu entfernen.

Antwort

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

• documentsDeleted — wie viele gespeicherte Dateien entfernt wurden.
• applicantDeleted — ob der Antragsteller als verwaister Datensatz bereinigt wurde (false, wenn er noch andere Anfragen hat).

Fehler

• 404 NOT_FOUND — keine Anfrage mit dieser ID in Ihrer Organisation.

Ergebnis melden

POST /api/v1/kyc/requests/:id/outcome    Berechtigungsbereich: kyc:write

Optional. Teilen Sie Certivant mit, ob der Kauf oder Kredit, für den die Verifizierung durchgeführt wurde, tatsächlich geliefert oder storniert wurde. Rufen Sie den Endpunkt auf, sobald über die Anfrage entschieden ist.

Request-Body

{ "fulfilled": true }

Antwort

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

recorded: false bedeutet, dass die Anfrage noch nicht im Betrugsnetzwerk ist (etwa weil keine Identitätsschlüssel vorliegen). Es geht nichts verloren — Sie können das Ergebnis später erneut senden. Sie können den Endpunkt auch jederzeit erneut aufrufen, um die Angabe zu ändern.

Fehler

• 404 NOT_FOUND — keine Anfrage mit dieser ID in dieser Organisation.
• 409 CONFLICT — über die Anfrage ist noch nicht entschieden. Ihr Status muss APPROVED, REJECTED, ESCALATED oder PENDING_SECOND_REVIEW sein.

Betrugssignale abrufen

GET /api/v1/kyc/requests/:id/fraud-signals    Berechtigungsbereich: kyc:read

Liefert die Geräte-, Netzwerk- und Verhaltenssignale zu Betrug, die während der Verifizierung erfasst wurden.

Antwort

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

Der Schweregrad ist low, medium oder high. Signale mit hohem Schweregrad eskalieren die Anfrage automatisch zur manuellen Prüfung.

Laufende AML-Überwachung

Eine genehmigte Verifizierung kann auf neue Treffer bei Sanktionen, PEP und negativen Medienberichten erneut geprüft werden (siehe Laufende Überwachung). Die Überwachung ist eine Funktion des Tarifs und wird pro überwachter Person und Jahr abgerechnet.

POST liefert 409 für eine Verifizierung, die nicht genehmigt ist, 403, wenn Ihr Tarif die Überwachung nicht enthält, und 402, wenn für eine Person über das inklusive Kontingent hinaus kein Guthaben vorhanden ist.

Neue Treffer kommen als Webhook kyc.monitoring.alert an (siehe Webhook-Ereignisse): data.monitoring enthält alertType (sanctions_match, pep_match, adverse_media, sanctions_unverifiable), severity und bei einer PEP die pepTier — 1 Staatsoberhäupter und Minister … 4 Verwandte und enge Vertraute — oder adverseMedia: true. data.sanctions.listsChecked nennt die geprüften Listen; die Anbieter der Prüfung werden niemals genannt.

Die Verifizierung selbst trägt dieselben pepTier / adverseMedia unter data.sanctions in ihrem Entscheidungs-Webhook.

Einen Antragsteller löschen (Löschung nach DSGVO)

DELETE /api/v1/kyc/applicants/:applicantId    Berechtigungsbereich: kyc:manage

Löscht einen Antragsteller und jede mit ihm verknüpfte Anfrage dauerhaft. Dies ist der Endpunkt für das Recht auf Löschung nach Artikel 17 DSGVO. Das Audit-Protokoll bewahrt einen Grabstein mit dem Zeitpunkt der Löschung, aber keine personenbezogenen Daten.

Antwort

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