> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Telefonverifizierung: Warnungen & Risiko-Codes

> Übersicht aller Risiko-Codes der Didit-Telefonverifizierung: HIGH_RISK_PHONE_NUMBER, VOIP_NUMBER_DETECTED, Sperrliste und OTP-Limits.

Die Funktion Telefonverifizierung gibt **Warnungen** aus, sobald ein Risikosignal im OTP-Ablauf oder für die Nummer selbst ausgelöst wird: eine bekannte betrügerische Nummer, ein VoIP- oder Einweganschluss, das Erreichen eines Limits für OTP-Versuche oder ein Treffer mit der Sitzung eines anderen Benutzers. Diese Seite listet alle Codes auf, was sie auslöst und wie Sie die Workflow-Reaktion konfigurieren.

## Übersicht

Warnungen sind mit der Funktion `PHONE` gekennzeichnet. Sie erscheinen unter `phone_verifications[].warnings[]` in `GET /v3/session/{sessionId}/decision/` und folgen der standardmäßigen Struktur des [Warnungsobjekts](https://docs.didit.me/de/reference/data-models.md#warnungsobjekt) (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`). Jede Warnung wird zudem in das sitzungsspezifische Protokoll geleitet, sodass sie in der Business Console im Bereich „Phone“ angezeigt wird.

Einige Warnungen sind Auslöser für eine **feste automatische Ablehnung** – sie setzen den Funktionsstatus immer auf `Declined`. Andere sind einer **konfigurierbaren Aktion** zugeordnet (`DECLINE`, `REVIEW` oder `NO_ACTION`, je nach Einstellung), die in Ihren Workflow-Einstellungen definiert ist, sodass derselbe Risiko-Code einen Workflow ablehnen kann, während er einen anderen lediglich markiert.

## Bedingungen für die automatische Ablehnung

Die folgenden Warnungen lehnen den Schritt der Telefonverifizierung unabhängig von der Konfiguration immer ab und weisen stets `log_type: "error"` auf:

* `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` — der Benutzer hat ein Limit für OTP-Versuche ausgeschöpft: standardmäßig 2 fehlerhafte Code-Eingaben (`phone_max_check_attempts`) oder mehr als 2 OTP-Versendungen (`phone_max_retries`), beides pro Workflow-Knoten anpassbar. Die eigenständige Telefon-API erlaubt 3 Code-Versuche.
* `PHONE_NUMBER_IN_BLOCKLIST` — die Nummer befindet sich in Ihrer über die [Lists API](https://docs.didit.me/de/management-api/lists/overview.md) verwalteten Sperrliste oder stimmt mit einer auf der Sperrliste geführten Sitzung überein.

`HIGH_RISK_PHONE_NUMBER` — die Betrugsbekämpfungsebene des Zustellanbieters verweigert den Versand des OTP (`Blocked`-Versand) — lehnt standardmäßig ab, ist jedoch **nicht mehr bedingungslos**: siehe [`high_risk_phone_action`](#blockierte-versendungen) unten.

## Konfigurierbare Risiken

Jedes der folgenden Risiken ist einer Workflow-Einstellung zugeordnet, die Sie auf `DECLINE`, `REVIEW` oder `NO_ACTION` konfigurieren können (die Standardeinstellung – die Warnung wird erfasst, ohne den Status zu beeinflussen). Die konfigurierte Aktion legt auch den `log_type` der Warnung fest: `DECLINE` → `error`, `REVIEW` → `warning`, `NO_ACTION` → `information`.

| Einstellung | Risiko-Code | Wird ausgelöst, wenn |
| - | - | - |
| `voip_number_action` | `VOIP_NUMBER_DETECTED` | Der Anschluss vom Netzbetreiber als Leitungstyp `voip`, `isp` oder `vpn` eingestuft wird. |
| `disposable_number_action` | `DISPOSABLE_NUMBER_DETECTED` | Die Abfrage den Anbieter der Nummer als temporären/Wegwerf-Anbieter kennzeichnet. |
| `duplicated_phone_number_action` | `DUPLICATED_PHONE_NUMBER` | Die Nummer mit einer anderen Sitzung mit beliebigem Status übereinstimmt, die zu einem anderen Endbenutzer gehört. Wird übersprungen, wenn die Nummer auf der Positivliste steht. |

Die Duplikaterkennung läuft innerhalb Ihrer Anwendung über KYC, KYB und eigenständige API-Telefonverifizierungen hinweg und gruppiert Sitzungen nach `vendor_data` – Sitzungen mit demselben `vendor_data`-Wert werden als ein einzelner Endbenutzer behandelt und von den Treffergebnissen ausgeschlossen. Bleibt `vendor_data` leer, wird jede Sitzung als eigenständiger Benutzer behandelt.

### Blockierte Versendungen

`HIGH_RISK_PHONE_NUMBER` folgt demselben Muster mit einem kleineren Auswahlsatz, da eine vom Anbieter verweigerte Versendung nicht genehmigt werden kann:

| Einstellung | Risiko-Code | Wird ausgelöst, wenn |
| - | - | - |
| `high_risk_phone_action` | `HIGH_RISK_PHONE_NUMBER` | Die Betrugsbekämpfungsebene des Zustellanbieters das Senden des OTP verweigert hat (`Blocked`-Versand). Akzeptiert nur `DECLINE` oder `REVIEW` und ist standardmäßig auf `DECLINE` gesetzt. |

Die Einstellung wird **nur dann angewendet, wenn jede Hochrisiko-Blockierung für den Schritt in `additional_data.risk_factors` exakt `["device_attribute"]` enthält** – das Signal des Anbieters „dieses Gerät sieht verdächtig aus“, das bei gewöhnlichen Mobilfunkanschlüssen anschlägt. Jeder andere Risikofaktor, jede Mischung, die `device_attribute` lediglich enthält, oder eine Blockierung ganz ohne Risikofaktoren führt unabhängig von der Einstellung zu einer Ablehnung. Der Grund für die Blockierung (`repeated_attempts`, `suspicious` oder `spam`) ist ein separates Feld, das in `additional_data.blocked_reason` zurückgegeben wird.

Unabhängig von der Einstellung wird eine Nummer auf einer über die [Lists API](https://docs.didit.me/de/management-api/lists/overview.md) erstellten Telefon-Positivliste bei einem blockierten Versand niemals automatisch abgelehnt: Der Schritt wechselt zu **In Prüfung**, die Warnung weist `log_type: "warning"` auf und `additional_data.phone_number_in_allowlist` ist `true`.

## Limits für Verifizierungsversuche

Die Funktion „Telefonverifizierung“ wendet eine feste Obergrenze für OTP-Versuche an, um Missbrauch zu verhindern:

* **Code-Eingabeversuche** — Standardmäßig **2** falsche Eingaben (`phone_max_check_attempts`), bevor der Schritt als `Declined` mit `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` abgeschlossen wird. Die Standalone-Telefon-API erlaubt **3** Code-Versuche pro Verifizierung.
* **Sendeversuche** — Standardmäßig insgesamt **2** Sendungen (`phone_max_retries`): der anfängliche Versand plus ein erneuter Versand. Eine weitere Sendeanfrage schließt den Schritt ab und löst `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` aus.
* **OTP-Gültigkeit** — Ein ausstehendes OTP ist für **5 Minuten ab dem ersten Versand** gültig; Wiederholungsversuche verlängern dieses Zeitfenster nicht.

Beide Obergrenzen sind pro Workflow-Knoten anpassbar. Unabhängig von diesen Obergrenzen kann die Betrugserkennung des Zustellanbieters einen Versand direkt blockieren (Grund `repeated_attempts`, `suspicious` oder `spam`) – dies löst `HIGH_RISK_PHONE_NUMBER` aus, nicht die Warnung zu Versuchen.

## Generierte Warnungen

| Tag | `log_type` | Beschreibung |
| - | - | - |
| `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` | `error` (immer) | Der Benutzer hat die Obergrenze für OTP-Code-Eingaben oder Sendeversuche überschritten. Wird automatisch abgelehnt. |
| `HIGH_RISK_PHONE_NUMBER` | Folgt `high_risk_phone_action` oder `warning`, wenn auf der Allowlist | Der Zustellanbieter hat den OTP-Versand blockiert. Wird standardmäßig abgelehnt; setzen Sie `high_risk_phone_action` auf `REVIEW`, um eine Blockierung, die ausschließlich auf Gerätesignalen basiert, stattdessen in den Status „In Prüfung“ weiterzuleiten (siehe [Blockierte Sendungen](#blockierte-versendungen)). Eine Nummer auf einer Telefon-Allowlist wird ebenfalls in den Status „In Prüfung“ versetzt. `additional_data`: `{ blocked_reason, risk_factors, phone_number_in_allowlist? }`. |
| `PHONE_NUMBER_IN_BLOCKLIST` | `error` (immer) | Die Nummer befindet sich auf einer Sperrliste, die über die [Lists API](https://docs.didit.me/de/management-api/lists/overview.md) erstellt wurde, oder stimmt mit einer Sitzung auf der Sperrliste überein. Wird automatisch abgelehnt. `additional_data`: `{ blocklisted_session_id, blocklisted_session_number, api_service }` (alle `null` bei einem reinen Listentreffer). |
| `PHONE_NUMBER_IN_ALLOWLIST` | `information` | Die Nummer stimmte mit anderen Sitzungen überein, befindet sich jedoch auf einer Allowlist, die über die [Lists API](https://docs.didit.me/de/management-api/lists/overview.md) erstellt wurde, sodass Aktionen für doppelte Telefonnummern übersprungen werden. `additional_data`: `{ phone_number }`. |
| `DISPOSABLE_NUMBER_DETECTED` | Folgt `disposable_number_action` | Die Nummer stammt von einem Anbieter für temporäre/Wegwerfnummern, die häufig verwendet werden, um die Rückverfolgbarkeit zu umgehen. |
| `VOIP_NUMBER_DETECTED` | Folgt `voip_number_action` | Die Nummer führt zu einem `voip`-, `isp`- oder `vpn`-Anschluss anstelle eines standardmäßigen Mobilfunk- oder Festnetzanschlusses. |
| `DUPLICATED_PHONE_NUMBER` | Folgt `duplicated_phone_number_action` | Die Nummer stimmt mit einer anderen Sitzung – unabhängig von deren Status – überein, die zu einem anderen Endbenutzer gehört (gruppiert nach `vendor_data`). `additional_data`: `{ duplicated_session_id, duplicated_session_number, api_service }`. |

## Sitzungsübergreifende Übereinstimmungen

Wenn eine Nummer in anderen Sitzungen oder auf Ihrer Sperrliste erkannt wird, erscheinen diese Treffer auch unter `phone_verifications[].matches[]` (begrenzt auf 5 Einträge). Jeder Treffer enthält `session_id`, `session_number`, `vendor_data`, `verification_date`, `phone_number`, `status`, `is_blocklisted`, `api_service` und den Wert `session` für `source` (eine andere Sitzung mit derselben Nummer, beliebiger Status) oder `list_entry` (ein synthetischer Sperrlistentreffer, der dem Array vorangestellt wird). Befindet sich die aktuelle Nummer auf Ihrer Telefon-Allowlist, behält Didit die Übereinstimmungsnachweise bei, gibt jedoch `PHONE_NUMBER_IN_ALLOWLIST` aus, anstatt die Aktion für doppelte Nummern anzuwenden. Siehe den [Bericht zur Telefonverifizierung](https://docs.didit.me/de/core-technology/phone-verification/report-phone-verification.md#sitzungsübergreifende-übereinstimmungen) für das vollständige Schema für Übereinstimmungen.

## Beispiel

Ein blockierter Versand (`HIGH_RISK_PHONE_NUMBER`) bei einer VoIP-Nummer, wobei `voip_number_action` auf `REVIEW` konfiguriert ist:

```json theme={null}
{
  "warnings": [
    {
      "feature": "PHONE",
      "risk": "HIGH_RISK_PHONE_NUMBER",
      "additional_data": { "blocked_reason": "suspicious" },
      "log_type": "error",
      "short_description": "High risk phone number",
      "long_description": "The system detected that the phone number is a high risk phone number, which is not allowed.",
      "node_id": "feature_phone_1"
    },
    {
      "feature": "PHONE",
      "risk": "VOIP_NUMBER_DETECTED",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "VoIP number detected",
      "long_description": "The system detected that the phone number is a VoIP number, which is not allowed.",
      "node_id": "feature_phone_1"
    }
  ]
}
```

## Warnungstypen

Jedem Risiko wird basierend auf der Konfiguration Ihrer Anwendung ein Schweregrad zugewiesen. Schweregrade unterteilen sich in drei Kategorien:

## Verwandte Themen

* [Übersicht zur Telefonverifizierung](https://docs.didit.me/de/core-technology/phone-verification/overview.md) — Funktionsverhalten, Preise, unterstützte Kanäle.
* [Bericht zur Telefonverifizierung](https://docs.didit.me/de/core-technology/phone-verification/report-phone-verification.md) — Vollständige Antwortstruktur einschließlich `lifecycle[]` und `matches[]`.
* [Datenmodelle – Telefonverifizierung](https://docs.didit.me/de/reference/data-models.md#telefonverifizierung) — Kanonisches Schema mit einer Beschreibung jedes Felds.
* [Management API – Listen](https://docs.didit.me/de/management-api/lists/overview.md) — Verwaltung der Telefon-Sperrliste, die von `PHONE_NUMBER_IN_BLOCKLIST` verwendet wird.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.