> ## 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.

# Telefonverifizierungs-API: OTP, SMS & WhatsApp

> Didit verifiziert Telefonnummern per OTP via SMS, WhatsApp, Telegram, RCS & Voice. $0.02 pro Abruf + Netzbetreiber, Carrier-Erkennung & Risikoscore.

Die Telefonverifizierung von Didit bietet eine zuverlässige Methode zur Verifizierung der Telefonnummern von Benutzern mittels Einmalcodes (OTP). Diese Funktion fügt Ihrem Identitätsverifizierungsprozess eine wesentliche Sicherheitsebene hinzu und stellt sicher, dass die Kontaktinformationen der Benutzer legitim sind.

Prompt zur Integration der Telefonverifizierung
        Prompt in die Zwischenablage kopieren



      
      

\<pre>

\````# Goal
Integrate Didit Phone Verification (OTP send + check + carrier/risk lookup) into your app. Pick ONE mode.

\# Mode A — Session-based
Use this when the user goes through a hosted Didit flow — the SDK collects the number and OTP for you.

1\. Add the PHONE feature to the workflow (Business Console or POST /v3/workflows/). Configure risk actions: duplicated_phone_number_action, disposable_number_action, voip_number_action.
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user (or mount the Web/Mobile SDK).
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

Decision surface: `phone_verifications[]` array on the decision payload.

\# Mode B — Standalone API (server-to-server, OTP pair)
Two endpoints, paired by phone_number.

Step 1 — send the code:
\```bash
curl -X POST 'https://verification.didit.me/v3/phone/send/' \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155552671",
"options": {
  "code_size": 6,
  "preferred_channel": "whatsapp",
  "locale": "en-US"
},
"vendor_data": "user-1234"
}'
\```
Channels: `whatsapp` (default), `sms`, `telegram`, `voice` — delivery falls back to SMS if the preferred channel is unavailable. Codes are valid for **5 minutes**; one free retry per number within the window.
Branding: SMS codes carry your app's SMS sender name ("123456 is your verification code for Acme Bank") on every send, at no extra cost; set it in the Business Console. Pass `options.sms_sender_name` to sign one code with another name (1 to 30 characters). WhatsApp codes use a fixed message; connect your own WhatsApp Business number in the Business Console to send them under your business name.

Step 2 — check the code (user types it into your UI):
\```bash
curl -X POST 'https://verification.didit.me/v3/phone/check/' \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155552671",
"code": "123456",
"voip_number_action": "DECLINE"
}'
\```
Each session accepts **up to 3** code-entry attempts. The check response includes the full phone metadata (carrier, line_type, disposable, voip, ported).

\# Status enum (per phone_verifications[].status / phone.status)
"Not Started" | "In Progress" | "Approved" | "Declined" | "Failed" | "Expired or Not Found" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.PHONE)
warnings[] risk codes include:
DUPLICATED_PHONE_NUMBER, DISPOSABLE_NUMBER, VOIP_NUMBER, INVALID_PHONE_NUMBER, OTP_DELIVERY_FAILED, OTP_MAX_ATTEMPTS_REACHED, OTP_EXPIRED, PHONE_NUMBER_BLOCKED.
Full catalogue: /core-technology/phone-verification/warnings-phone-verification.

\# Failure modes to handle
\- HTTP 400 — non-E.164 phone_number on /send/.
\- send response status="Blocked" with reason="spam" — anti-abuse block; no code sent, no charge.
\- check response status="Failed" — wrong code, attempts remaining; re-prompt.
\- check response status="Declined" — third failed attempt; restart with /v3/phone/send/.
\- check response status="Expired or Not Found" — outside the 5-minute window or no pending session for that number; restart.

\# See also
\- Canonical schema: /reference/data-models#phone-verification
\- Per-feature report: /core-technology/phone-verification/report-phone-verification
\- Risk catalogue: /core-technology/phone-verification/warnings-phone-verification
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Einfügen in

In der Academy-Lektion zum Auslesen eines Verifizierungsergebnisses behandelt das Kapitel bei 8:08 die Telefonverifizierung und die Duplikatserkennung.[Telefonverifizierung und Duplikate — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=488\&rel=0\&playsinline=1)![Ablaufdiagramm der Telefonverifizierung](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/phone-verification-flow.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=6c12863ce97e5ad6a11757b598918932)## FunktionsweiseUnsere Telefonverifizierungslösung bietet eine umfassende Validierung von Telefonnummern über einen einfachen, benutzerfreundlichen Prozess. Das System kombiniert die OTP-Verifizierung mit einer fortschrittlichen Risikobewertung, um eine zuverlässige Telefonverifizierung im großen Maßstab zu ermöglichen.**1. Erfassung der Telefonnummer**Das System erfasst die folgenden Informationen sicher:| Erfasste Daten | Details |
| - | - |
| **Telefonnummer** | Wenn sie bei der Sitzungserstellung nicht angegeben wurde, gibt der Benutzer seine Telefonnummer im internationalen Format ein. Wenn sie angegeben wurde, muss der Benutzer die vorausgefüllte Nummer verifizieren. |
| **Ländervorwahl** | Wird automatisch anhand des IP-Standorts oder der Benutzerauswahl vorgeschlagen. |
| **Netzbetreibertyp** | Erkennt, ob es sich um eine Mobilfunk- oder Festnetznummer handelt. |**2. OTP-Generierung & Zustellung**Unser Verifizierungssystem:- Generiert einen sicheren, zeitlich begrenzten Einmalcode
- Stellt den Code per SMS an die angegebene Nummer zu
- Gewährleistet eine optimierte Zustellung über Integrationen mit mehreren Mobilfunkanbietern
- Bietet Fallback-Optionen bei Zustellungsproblemen**3. Code-Validierung**Der Benutzer schließt die Verifizierung wie folgt ab:- Eingabe des empfangenen Codes in die Verifizierungsoberfläche
- Übermittlung innerhalb des konfigurierten Zeitfensters (üblicherweise 5–10 Minuten)
- Anfordern eines neuen Codes bei Bedarf (mit angemessenem Rate-Limit)**4. Risikobewertung**Unser System führt fortschrittliche Prüfungen durch:| Prüfung | Beschreibung |
| - | - |
| **Format & Netzbetreiber** | Verifiziert das Format der Telefonnummer und Informationen zum Anbieter. |
| **Wegwerfnummern** | Gleicht Daten mit bekannten Datenbanken für Wegwerf- und virtuelle Nummern ab. |
| **SIM-Swap-Erkennung** | Identifiziert potenzielle Risiken durch SIM-Swaps. |
| **Aktivitätsmuster** | Erkennt verdächtige Aktivitätsmuster. |
| **Historische Daten** | Führt einen Abgleich mit historischen Verifizierungsdaten durch. |**5. Ergebnisübermittlung**Greifen Sie über mehrere Kanäle auf Verifizierungsergebnisse zu:| Kanal | Beschreibung |
| - | - |
| **Dashboard** | Dashboard-Aktualisierungen in Echtzeit. |
| **Webhooks** | Sofortige Webhook-Benachrichtigungen. |
| **API** | RESTful-API-Integration. |
| **Berichte** | Umfassende Berichte mit detaillierten Verifizierungsinformationen. |## VerifizierungsfunktionenUnser Telefonverifizierungs-Service bietet mehrere wichtige Funktionen zur Optimierung Ihres Verifizierungsprozesses:#### OTP-Verifizierung- **Sichere Codegenerierung**: Zufällig generierte Einmalcodes
- **SMS-Zustellung**: Schnelle und zuverlässige Zustellung an Mobilgeräte
- **Konfigurierbare Timeouts**: Legen Sie Ablaufzeiten basierend auf Ihren Sicherheitsanforderungen fest
- **Wiederholungsoptionen**: Ermöglichen Sie Benutzern das Anfordern neuer Codes mit einem angemessenen Rate-Limit
- **Gebrandete Codes**: SMS-Codes nennen Ihre Marke, anstatt eine generische Nachricht zu senden – ohne zusätzliche Kosten. Siehe [Gebrandete Verifizierungsnachrichten](#gebrandete-verifizierungsnachrichten).
- **Eigene WhatsApp-Nummer**: WhatsApp-Codes können von Ihrer eigenen WhatsApp-Business-Nummer stammen. Siehe [WhatsApp-Codes von Ihrer eigenen Nummer senden](#whatsapp-codes-von-ihrer-eigenen-nummer-senden).#### Gebrandete VerifizierungsnachrichtenSMS-Verifizierungscodes können Ihre Marke nennen, damit Ihre Benutzer die Nachricht als Ihre erkennen:> 123456 ist Ihr Verifizierungscode für **Acme Bank**Nur der Name kann angepasst werden.
Der Rest des Wortlauts ist ein Standardtext, der bei Mobilfunkanbietern in jedem Land registriert ist, was verhindert, dass Codes als Spam gefiltert werden, und er wird in die Sprache des Empfängers übersetzt.
Branding ist kostenlos: Ein gebrandeter Code kostet genauso viel wie ein ungebrandeter.**Legen Sie Ihren SMS-Absendernamen fest** in der Business Console unter **Phone Verification → Settings** eines Workflows oder unter **White Label → SMS**.
Er gehört zu Ihrer Anwendung, nicht zu einem einzelnen Workflow: Er signiert jeden SMS-Code, den die Anwendung sendet, in jedem Workflow und über die Standalone-API, mit oder ohne White-Label-Anpassung.**Welchen Namen ein Code trägt**, die erste Übereinstimmung gilt:1) `options.sms_sender_name` bei [`POST /v3/phone/send/`](https://docs.didit.me/de/standalone-apis/phone-send), für diesen einzelnen Code.
2) Der SMS-Absendername Ihrer Anwendung.
3) Nur bei White-Label-Versendungen (ein Workflow mit White-Label-Anpassung oder `options.use_white_label_customization: true` über die API): Ihr öffentlicher White-Label-Name.
4) Andernfalls wird der Code ohne Namen gesendet.Ein Absendername umfasst 1 bis 30 Zeichen: nur Buchstaben, Ziffern, Leerzeichen sowie ' & - !, nicht nur Ziffern, mit jeweils einem Leerzeichen zwischen Wörtern.
Die API weist einen Namen außerhalb dieser Regeln mit `400` ab, bevor ein Code gesendet wird.- **Kanäle**: Der Name wird zu SMS-Nachrichten hinzugefügt, einschließlich einer SMS, die als Fallback von einem anderen Kanal gesendet wird. WhatsApp-Codes werden mit einer festen Nachricht gesendet und enthalten ihn nicht; um Ihren Unternehmensnamen darauf anzuzeigen, [senden Sie sie von Ihrer eigenen Nummer](#whatsapp-codes-von-ihrer-eigenen-nummer-senden).
- **Änderungen pro Tag**: Jede Anwendung kann pro Tag (UTC) bis zu zwei neue Namen in Betrieb nehmen, wobei sowohl neue Absendernamen als auch neue `sms_sender_name`-Werte zählen. Danach behalten Codes bis zum nächsten Tag den aktuellen Namen der Anwendung, und ein neuer Name pro Anfrage wird mit dem Namen der Anwendung gesendet. Ein zuvor bereits verwendeter Name zählt nicht erneut.
- **Zustellung hat Vorrang**: Ein Branding-Problem hält einen Code niemals auf. Wenn ein Name nicht angewendet werden kann, wird der Code mit dem Namen der Anwendung oder ohne Namen gesendet.#### Eigenen SMS-Text und eigene Absender-ID festlegenSie können den Text Ihrer SMS-Codes und den Absender, den Ihre Benutzer sehen, ersetzen.
Legen Sie beides in der Business Console unter **White Label → SMS** fest.
Sie gehören wie der SMS-Absendername zu Ihrer Anwendung und gelten für jeden SMS-Code, den sie sendet – in jedem Workflow und über die Standalone-API.**Ihr eigener Text** wird pro Sprache verfasst.
Ein Code wird mit Ihrem Text gesendet, wenn Sie einen für die Sprache verfasst haben, in der der Code gesendet wird; alle anderen Sprachen behalten den übersetzten Text von Didit.
Verwenden Sie `{code}` für den Code und optional `{brand}` für Ihren SMS-Absendernamen, zum Beispiel `Acme: {code} is your login code for {brand}.`Ein Text muss:- `{code}` genau einmal enthalten und keinen anderen Platzhalter außer `{code}` und `{brand}`;
- keine Links enthalten: Mobilfunkanbieter blockieren Verifizierungscodes, die Links enthalten;
- mit einem 8-stelligen Code und einem 30-Zeichen-Namen in eine einzelne SMS passen: bis zu 160 Zeichen oder 70, wenn Zeichen außerhalb des lateinischen Basisalphabets verwendet werden (beispielsweise kyrillisch, arabisch oder Emojis).**Ihre eigene Absender-ID** verwendet 3 bis 11 Buchstaben, Ziffern und Leerzeichen, nicht nur Ziffern, zum Beispiel `AcmeBank`.
Sie wird in den Ländern verwendet, in denen Didit benutzerdefinierte Absender-IDs aktiviert – das sind die Länder, deren Mobilfunkanbieter einen Absendernamen ohne vorherige Registrierung akzeptieren; überall sonst werden Ihre Codes unter dem Absender von Didit versendet.
Wenden Sie sich an den Support, um ein Land anzufragen, bei dem der Absender registriert werden muss.- **Zustellung hat Vorrang**: Wenn ein Code über eine Route erneut gesendet wird, die Ihren Text oder Ihre Absender-ID nicht übermitteln kann, wird er mit Didits Text, Ihrem SMS-Absendernamen und Didits Absender gesendet, damit der Code immer ankommt.#### WhatsApp-Codes von Ihrer eigenen Nummer sendenStandardmäßig stammen WhatsApp-Codes von Didits WhatsApp-Business-Nummer.
Sie können stattdessen Ihre eigene WhatsApp-Business-Nummer verknüpfen, sodass Ihre Benutzer ihre Codes unter Ihrem Unternehmensnamen und Ihrer Nummer erhalten.**Verknüpfen Sie eine Nummer** in der Business Console unter **Phone Verification → Settings → WhatsApp number** eines Workflows und wählen Sie **Connect WhatsApp number**.
Ein Anmeldefenster öffnet sich: Melden Sie sich bei dem Unternehmenskonto an, das Ihre WhatsApp-Business-Nummer verwaltet, und wählen Sie dann das WhatsApp-Business-Konto sowie die Nummer aus, von der gesendet werden soll.
Didit registriert die Nummer anschließend für den Versand und erstellt deren Verifizierungsnachricht.
Dafür ist die Berechtigung zum Bearbeiten von Anpassungen erforderlich, wie auch beim SMS-Absendernamen.Die Nummer gehört zu Ihrer Anwendung, nicht zu einem einzelnen Workflow: Sobald sie verknüpft ist, sendet sie jeden WhatsApp-Code, den die Anwendung sendet – in jedem Workflow und über die Standalone-API.- **Genehmigung**: Die neue Verifizierungsnachricht benötigt eine Genehmigung, bevor die Nummer Codes senden kann, in der Regel innerhalb weniger Minuten. Die Karte zeigt die Nummer bis dahin als auf Genehmigung wartend an, und Codes werden in der Zwischenzeit weiterhin von Didits Nummer versendet.
- **Nachrichtentext**: Verifizierungsnachrichten auf WhatsApp verwenden einen Standardtext in der Sprache Ihres Benutzers: den Code, einen Sicherheitshinweis und eine Schaltfläche zum Kopieren. Der Text kann nicht bearbeitet werden, aber der Absender ist Ihr Unternehmen.
- **Zustellung**: Wenn ein Code nicht über WhatsApp zugestellt werden kann, wird er per SMS gesendet, signiert mit Ihrem SMS-Absendernamen.
- **Abrechnung**: Die von Ihrer Nummer gesendeten Nachrichten werden über Ihr WhatsApp-Business-Konto abgerechnet, sodass Didit für diese Codes nur seine Verifizierungsgebühr (\$0.02) berechnet. Per SMS gesendete Codes werden wie gewohnt abgerechnet.
- **Handlungsbedarf**: Wenn die Nummer nicht mehr senden kann (wenn beispielsweise der Zugriff aus Ihrem Unternehmenskonto entfernt wurde), werden Codes wieder von Didits Nummer gesendet und die Karte fordert Sie auf, die Nummer erneut zu verknüpfen.
- **Trennen** Sie die Verbindung jederzeit über dieselbe Karte. Codes werden wieder von Didits Nummer gesendet; die Nummer und ihre Verifizierungsnachricht verbleiben in Ihrem WhatsApp-Business-Konto.#### Telefonnummernanalyse- **Formatvalidierung**: Sicherstellen, dass die Telefonnummer dem korrekten internationalen Format entspricht
- **Netzbetreibererkennung**: Den mit der Nummer verknüpften Telekommunikationsanbieter identifizieren
- **Nummerntyp**: Zwischen Mobilfunk-, Festnetz- und VoIP-Nummern unterscheiden
- **Ländervalidierung**: Überprüfen, ob die Telefonnummer dem erwarteten Länderformat entspricht#### Risikobewertung- **Erkennung von Wegwerfnummern**: Temporäre Nummern identifizieren, die verwendet werden, um eine Rückverfolgung zu vermeiden
- **Identifizierung virtueller Nummern**: Nummern kennzeichnen, bei denen es sich um virtuelle oder VoIP-basierte Nummern handeln könnte
- **Aktivitätsüberwachung**: Verdächtige Muster über Verifizierungsversuche hinweg nachverfolgen
- **Sperrlistenprüfung**: Abgleich mit internen Listen zuvor missbräuchlich genutzter Nummern## PreiseDie Telefonverifizierung wird **pro gesendeter Nachricht** mit transparenten, nutzungsabhängigen Preisen abgerechnet:| Komponente | Kosten |
| - | - |
| **Didit-Gebühr** | \$0.02 pro Verifizierung |
| **Netzbetreibergebühr** | Variiert je nach Land und Kanal |
| **Gesamt** | \$0.02 + Netzbetreibergebühr |Ihr Tarifrabatt gilt ausschließlich für die Didit-Gebühr von \$0.02; die Netzbetreibergebühr wird zum Selbstkostenpreis weitergegeben und niemals rabattiert. Siehe [Rabatte](https://docs.didit.me/de/getting-started/pricing.md#rabatte).Wir unterstützen mehrere Zustellungskanäle mit unterschiedlichen Preisen (die Verfügbarkeit variiert je nach Land):| Kanal | Beschreibung |
| - | - |
| **SMS** | Traditionelle SMS-Zustellung |
| **WhatsApp** | Zustellung per WhatsApp-Nachricht |
| **Telegram** | Zustellung per Telegram-Nachricht |
| **RCS** | Zustellung per Rich Communication Services (RCS) |
| **Viber** | Zustellung per Viber-Nachricht |
| **Zalo** | Zustellung per Zalo-Nachricht (Vietnam) |> [!NOTE]
>
> Sie zahlen nur, wenn eine Nachricht gesendet wird. Wenn der Benutzer vor der OTP-Zustellung abbricht, werden Ihnen keine Kosten berechnet.→ [Preise für die Telefonverifizierung](https://docs.didit.me/de/getting-started/phone-verification-pricing.md)


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