Sperrlisten-API

Die Sperrliste ist dieselbe Liste wie Einstellungen → Betrugsprävention im Dashboard (siehe Sperrliste und Erkennung von Dubletten). Eine Verifizierung, die auf einen aktiven Eintrag passt, wird abgelehnt oder zur manuellen Prüfung weitergeleitet. Die Einträge sind nur für Ihre Organisation sichtbar.

Die Endpunkte liegen unter /api/v1/kyc/blocklist und verwenden einen API-Schlüssel (Authorization: Bearer ck_live_…) mit dem Berechtigungsbereich kyc:manage. Siehe Authentifizierung.

Gesperrte Werte werden nie zurückgegeben: Die API liefert den Eintragstyp, einen maskierten Hinweis (eine IP-Adresse oder ein Bereich wird vollständig zurückgegeben), die Aktion, den Grund, das Ablaufdatum und die Trefferzähler.

Einträge hinzufügen

POST /api/v1/kyc/blocklist

Einen typisierten Wert sperren:

{
  "kind": "email",
  "value": "fraud@example.com",
  "action": "reject",
  "reason": "Chargeback ring",
  "expiresAt": "2027-01-01T00:00:00.000Z"
}

Oder sperren Sie, was eine bestehende Verifizierung enthält:

{
  "fromRequestId": "clx…",
  "kinds": ["face", "device", "ip"],
  "action": "escalate"
}

fromRequestId muss eine Verifizierung Ihrer Organisation sein. kinds begrenzt, was gesperrt wird (Standard: alles, was die Verifizierung enthält: Gesicht, Dokumentnummer(n), Telefonnummer, E-Mail-Adresse, IP-Adresse, Gerät). Arten, zu denen die Verifizierung keine Daten hat, werden übersprungen.

Antwort 201:

{
  "data": [
    {
      "id": "clx…",
      "kind": "email",
      "valueHint": "f•••@e•••.com",
      "action": "reject",
      "reason": "Chargeback ring",
      "createdByName": null,
      "sourceRequestId": null,
      "expiresAt": "2027-01-01T00:00:00.000Z",
      "expired": false,
      "matchCount": 0,
      "lastMatchedAt": null,
      "createdAt": "2026-10-24T15:00:00.000Z"
    }
  ]
}

Fehler: 400 bei einem unbrauchbaren Wert oder einer Verifizierung, aus der nichts zu sperren ist, 404, wenn fromRequestId nicht Ihre ist, 409, wenn bereits ein identischer aktiver Eintrag existiert.

Einträge auflisten

GET /api/v1/kyc/blocklist?kind=email&includeExpired=false&page=1&pageSize=50

Liefert { "data": [ … ], "total": 12 }. Abgelaufene Einträge werden ausgeblendet, sofern nicht includeExpired=true gesetzt ist. pageSize beträgt höchstens 200.

Einen Eintrag entfernen

DELETE /api/v1/kyc/blocklist/:id → { "success": true }. Das Entfernen eines Eintrags, der nicht Ihrer ist, liefert 404.

Jedes Hinzufügen und Entfernen wird im Audit-Protokoll festgehalten, wobei der API-Schlüssel als Akteur vermerkt wird.

Das Ergebnis auswerten

Eine Verifizierung, die einen Treffer hat, enthält einen Eintrag blocklist_match in ihren Betrugssignalen (GET /api/v1/kyc/requests/:id/fraud-signals), mit details.kind (der Typ) und details.action, niemals aber dem Wert. Ihre Prüfauslöser oder Ausschlussgründe enthalten blocklist_match, und Richtlinien- sowie Workflow-Regeln können fraud.blocklistMatch und fraud.blocklistKinds prüfen.