Telefonverifizierungsbericht: OTP- & Carrier-JSON

Der Bericht zur Telefonverifizierung erfasst das vollständige Ergebnis einer Telefon-OTP-Abfrage: an wen der Code gesendet wurde, welcher Mobilfunkanbieter und welcher Kanal ihn übermittelt haben, wie viele Versuche erforderlich waren, ob es sich um eine Wegwerf- oder VoIP-Nummer handelt, sowie alle sitzungsübergreifenden Übereinstimmungen mit Ihrer Sperrliste oder Sitzungen anderer Benutzer. Diese Seite dokumentiert die JSON-Struktur, die vom Entscheidungs-Endpoint zurückgegeben wird, damit Sie OTP-Ergebnisse, Mobilfunkanbieter-Metadaten und Risikoflags für jede verifizierte Nummer parsen können.

Didit-Bericht zur Telefonverifizierung mit OTP-Ergebnis, Mobilfunkanbieter-Metadaten und Risikoflags

Übersicht

Ein Telefonbericht wird jedes Mal erstellt, wenn ein Workflow-Knoten die Funktion „Telefonverifizierung“ ausführt. Jeder Bericht stellt eine OTP-Abfrage für eine Telefonnummer dar und enthält:

Die Telefonnummer, aufgeschlüsselt in Vorwahl, nationale Rufnummer und vollständiges E.164-Format, sowie ISO-Ländercode und Ländername.
Mobilfunkanbieter-Metadaten (name, type), die über das Zielnetzwerk ermittelt wurden.
Boolesche Risikoflags (is_disposable, is_virtual), die aus der Leitungstypanalyse abgeleitet werden.
Den tatsächlich verwendeten Zustellkanal (verification_method) und die Anzahl der OTP-Sendeversuche.
Ein chronologisches lifecycle[]-Protokoll jedes Sende-, Wiederholungs- und Zustellungsereignisses sowie jedes Code-Prüfungsversuchs.
Ein matches[]-Array, das dieselbe Nummer in anderen Sitzungen anzeigt – unabhängig vom Status, über KYC, KYB und eigenständige API-Verifizierungen hinweg – oder auf Ihrer Sperrliste.
Ein warnings[]-Array – Risikoereignisse, die während der Verifizierung ausgegeben wurden (siehe Warnungen der Telefonverifizierung).
Eine node_id, die angibt, welcher Workflow-Graph-Knoten den Bericht erstellt hat (nur V3-Sitzungen).

Bei gehosteten Verifizierungsabläufen führt Didit den OTP-Austausch für Sie durch. Bei direkten API-Integrationen besteht derselbe Ablauf aus zwei Aufrufen – POST /v3/phone/send/ zur Zustellung des Codes und POST /v3/phone/check/ zur Validierung der Benutzereingabe. Ein ausstehendes OTP ist ab dem ersten Senden 5 Minuten lang gültig (Wiederholungsversuche verlängern das Zeitfenster nicht). In Workflow-Sitzungen stehen Benutzern standardmäßig 2 OTP-Sendeversuche (phone_max_retries) und 2 Codeeingabeversuche (phone_max_check_attempts) zur Verfügung – beides lässt sich pro Workflow-Knoten anpassen; das Erreichen eines der beiden Limits schließt den Schritt als Declined mit VERIFICATION_CODE_ATTEMPTS_EXCEEDED ab. Die eigenständige Telefon-API erlaubt 3 Codeeingabeversuche pro Verifizierung.

Wo es in API-Antworten erscheint

Der Entscheidungs-Endpoint (GET /v3/session/{sessionId}/decision/) gibt Telefonberichte unter dem Plural-Array-Schlüssel phone_verifications zurück. Das Array enthält einen Eintrag pro Telefonverifizierungsknoten im Workflow-Graph – typischerweise einen; Step-up-Abläufe können jedoch mehrere erzeugen.

{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "status": "Approved",
  "phone_verifications": [
    { "status": "Approved", "node_id": "feature_phone_1", "...": "..." }
  ]
}

Ein null-Wert bedeutet, dass noch kein Telefonverifizierungsschritt ausgeführt wurde. Iterieren Sie über das Array (anstatt phone_verifications[0] auszulesen), wenn Ihr Workflow mehr als eine Telefonnummer erfassen kann.

Schema

Das kanonische feldbasierte Schema finden Sie auf der Seite Datenmodelle.

interface PhoneVerification {
  status: "Not Finished" | "Approved" | "Declined" | "In Review" | "Expired";
  phone_number_prefix: string;       // E.g. "+34"
  phone_number: string;              // National number, no prefix
  full_number: string;               // Full E.164, e.g. "+34600600600"
  country_code: string;              // ISO 3166-1 alpha-2, e.g. "ES"
  country_name: string;
  carrier: {
    name: string;
    type:                              // From LineTypeChoices
      | "mobile" | "fixed_line" | "voip" | "isp" | "vpn"
      | "toll_free" | "premium_rate" | "shared_cost" | "local_rate"
      | "satellite" | "pager" | "payphone" | "voice_mail"
      | "calling_cards" | "service" | "short_codes_commercial"
      | "universal_access" | "other" | "unknown";
  };
  is_disposable: boolean;            // Temporary / burner number
  is_virtual: boolean;               // true when carrier.type is voip, isp or vpn
  verification_method:               // Actual channel that delivered the OTP
    | "sms" | "whatsapp" | "telegram" | "voice" | "rcs" | "viber" | "zalo";
  verification_attempts: number;     // OTP send attempts (initial send + resends)
  verified_at: string | null;        // ISO 8601, set when a valid OTP was entered
  warnings: Warning[];               // Risk events emitted during verification
  lifecycle: PhoneLifecycleEvent[];  // OTP send/retry/delivery/check timeline
  matches: PhoneMatch[];             // Cross-session / blocklist matches (max 5)
  node_id: string;                   // Workflow graph node that produced this report
}

Statuswerte

Status	Bedeutung
`Not Finished`	Der OTP-Versand wurde initiiert, die Verifizierung wurde jedoch noch nicht abgeschlossen.
`Approved`	Der Benutzer hat ein gültiges OTP eingegeben und keine ablehnende Risikoregel griff.
`Declined`	Eine Warnung zur automatischen Ablehnung wurde ausgelöst (Sperrliste, hohes Risiko, maximale Anzahl an Versuchen überschritten) oder eine auf `DECLINE` konfigurierte Risikoaktion traf zu.
`In Review`	Eine auf `REVIEW` konfigurierte Risikoaktion hat den Schritt an die manuelle Prüfung weitergeleitet.
`Expired`	Das 5-minütige OTP-Zeitfenster ist ohne gültigen Code abgelaufen – gilt für Verifizierungen, die über die Standalone-Telefon-API erstellt wurden.

Lifecycle-Ereignistypen

lifecycle[] ist chronologisch sortiert. Jedes Ereignis enthält type, timestamp, details und eine abrechenbare fee (sofern zutreffend):

Ereignistyp	Ausgelöst wenn
`PHONE_VERIFICATION_MESSAGE_SENT`	Erster OTP-Sendeversuch über den angeforderten Kanal.
`PHONE_VERIFICATION_RETRY_MESSAGE_SENT`	Nachfolgender OTP-Versand, nachdem der Benutzer ein erneutes Senden angefordert hat.
`PHONE_VERIFICATION_BLOCKED`	Der Versand wurde blockiert (Spam, verdächtig, wiederholte Versuche, ungültige Nummer).
`PHONE_DELIVERY_DELIVERED`	Carrier hat die Zustellung auf dem tatsächlich verwendeten Kanal bestätigt.
`PHONE_DELIVERY_UNDELIVERABLE`	Carrier hat gemeldet, dass die Nachricht nicht zugestellt werden konnte.
`VALID_CODE_ENTERED`	Der Benutzer hat den korrekten OTP-Code übermittelt.
`INVALID_CODE_ENTERED`	Der Benutzer hat einen falschen OTP-Code übermittelt (zählt zum Limit für Code-Eingaben).
`PHONE_VERIFICATION_APPROVED`	Der Status auf Funktionsebene wurde auf `Approved` gesetzt.
`PHONE_VERIFICATION_DECLINED`	Der Status auf Funktionsebene wurde auf `Declined` gesetzt.
`PHONE_VERIFICATION_IN_REVIEW`	Der Status auf Funktionsebene wurde auf `In Review` gesetzt.
`PHONE_VERIFICATION_EXPIRED`	Das OTP-Zeitfenster ist ohne gültigen Code abgelaufen.

Die details-Payload hängt von der Ereignisfamilie ab:

Sendeereignisse (PHONE_VERIFICATION_MESSAGE_SENT, PHONE_VERIFICATION_RETRY_MESSAGE_SENT, PHONE_VERIFICATION_BLOCKED) – { status, reason, channel, actual_channel }. status ist Success, Retry oder Blocked; reason ist null, es sei denn, der Versand wurde blockiert (invalid_phone_number, repeated_attempts, suspicious, spam, unknown); channel ist der angeforderte Kanal und actual_channel der Kanal, über den tatsächlich zugestellt wurde (z. B. ein WhatsApp-Versand mit Fallback auf SMS).
Zustellungsereignisse (PHONE_DELIVERY_DELIVERED, PHONE_DELIVERY_UNDELIVERABLE) – { channel, status } mit status als delivered oder undeliverable.
Prüfungsereignisse (VALID_CODE_ENTERED, INVALID_CODE_ENTERED) – { code_tried, status } mit status als Approved, Declined, Failed oder Expired or Not Found.
Endstatusereignisse – null, außer PHONE_VERIFICATION_DECLINED / PHONE_VERIFICATION_IN_REVIEW, die { "reason": "<risk code>" } enthalten (z. B. PHONE_NUMBER_IN_BLOCKLIST).

fee bei einem Sendeereignis ist der Gesamtpreis dieses Versands: der Carrier- oder WhatsApp-Preis zuzüglich der Didit-Gebühr von $0.02 bzw. nur die Didit-Gebühr von $0.02 für einen WhatsApp-Code, der über Ihre eigene WhatsApp Business-Nummer gesendet wurde. Es ist der geschätzte Preis, bis die Zustellung bestätigt wird, und danach der tatsächlich in Rechnung gestellte Betrag. Nur Blocked-Sendungen sind garantiert kostenlos: Jeder andere Versand wird berechnet, sobald die Verifizierung abgeschlossen ist oder abläuft, selbst wenn die Zustellung nie bestätigt wurde oder die Nachricht unzustellbar war. Zustellungs-, Prüfungs- und Statusereignisse enthalten immer fee: 0.

Sitzungsübergreifende Übereinstimmungen

matches[] erfasst andere Sitzungen in derselben Anwendung, bei denen dieselbe Nummer aufgetreten ist – über KYC-, KYB- und eigenständige API-Verifizierungen hinweg, unabhängig von ihrem Status – sowie Sperrlistentreffer, die in den Management-API-Listen konfiguriert sind. Sitzungen, die dieselben vendor_data wie die aktuelle Sitzung aufweisen, werden ausgeschlossen (derselbe Endbenutzer wird nicht mit sich selbst abgeglichen), und das Array ist auf 5 Einträge begrenzt. Wenn die Nummer auf Ihrer Sperrliste steht, aber keine der übereinstimmenden Sitzungen auf der Sperrliste geführt wird, wird dem Array ein synthetischer Eintrag mit source: "list_entry" (alle Sitzungsfelder null) vorangestellt.

interface PhoneMatch {
  session_id: string | null;         // null when source = "list_entry"
  session_number: number | null;
  vendor_data: string | null;
  verification_date: string | null;  // ISO 8601, creation date of the matched session
  phone_number: string;
  status: string | null;             // Status of the matched session
  is_blocklisted: boolean;
  api_service: string | null;        // Set when the matched session came from a standalone API
  source: "session" | "list_entry";  // "list_entry" = manual blocklist hit
}

Beispiele

Approved – WhatsApp-OTP, Mobilfunkanbieter

{
  "status": "Approved",
  "phone_number_prefix": "+34",
  "phone_number": "600600600",
  "full_number": "+34600600600",
  "country_code": "ES",
  "country_name": "Spain",
  "carrier": { "name": "Orange", "type": "mobile" },
  "is_disposable": false,
  "is_virtual": false,
  "verification_method": "whatsapp",
  "verification_attempts": 1,
  "verified_at": "2025-08-24T09:12:39.684292Z",
  "warnings": [],
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-08-24T09:12:30.580554Z",
      "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" },
      "fee": 0.0509
    },
    {
      "type": "PHONE_DELIVERY_DELIVERED",
      "timestamp": "2025-08-24T09:12:31.000000Z",
      "details": { "channel": "whatsapp", "status": "delivered" },
      "fee": 0
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2025-08-24T09:12:39.662157Z",
      "details": { "code_tried": "123456", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_APPROVED",
      "timestamp": "2025-08-24T09:12:39.684292Z",
      "details": null,
      "fee": 0
    }
  ],
  "matches": [],
  "node_id": "feature_phone_1"
}

Declined – VoIP-Nummer auf Sperrliste

Der Benutzer hat ein gültiges OTP eingegeben, aber beim Abschluss wurde die Nummer auf der Sperrliste der Anwendung gefunden (automatische Ablehnung) und der Leitungstyp der Nummer als VoIP gekennzeichnet (voip_number_action verblieb auf NO_ACTION, weshalb sie als information protokolliert wird). Da keine der übereinstimmenden Sitzungen auf der Sperrliste steht, erscheint der Sperrlistentreffer als synthetischer list_entry-Treffer.

{
  "status": "Declined",
  "phone_number_prefix": "+1",
  "phone_number": "5551234567",
  "full_number": "+15551234567",
  "country_code": "US",
  "country_name": "United States",
  "carrier": { "name": "VoIP Carrier", "type": "voip" },
  "is_disposable": false,
  "is_virtual": true,
  "verification_method": "sms",
  "verification_attempts": 1,
  "verified_at": "2025-08-24T09:11:10.221340Z",
  "warnings": [
    {
      "feature": "PHONE",
      "risk": "PHONE_NUMBER_IN_BLOCKLIST",
      "additional_data": { "blocklisted_session_id": null, "blocklisted_session_number": null, "api_service": null },
      "log_type": "error",
      "short_description": "Phone number in blocklist",
      "long_description": "The system detected that the phone number is in the blocklist, which is not allowed.",
      "node_id": "feature_phone_1"
    },
    {
      "feature": "PHONE",
      "risk": "VOIP_NUMBER_DETECTED",
      "additional_data": null,
      "log_type": "information",
      "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"
    }
  ],
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-08-24T09:11:00.000000Z",
      "details": { "status": "Success", "reason": null, "channel": "sms", "actual_channel": "sms" },
      "fee": 0.0509
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2025-08-24T09:11:10.221340Z",
      "details": { "code_tried": "482917", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_DECLINED",
      "timestamp": "2025-08-24T09:11:10.350000Z",
      "details": { "reason": "PHONE_NUMBER_IN_BLOCKLIST" },
      "fee": 0
    }
  ],
  "matches": [
    {
      "session_id": null,
      "session_number": null,
      "vendor_data": null,
      "verification_date": null,
      "phone_number": "+15551234567",
      "status": null,
      "is_blocklisted": true,
      "api_service": null,
      "source": "list_entry"
    }
  ],
  "node_id": "feature_phone_1"
}

Authentifizierung

Verifizierung

Überwachung

Plattform

Telefonverifizierungsbericht: OTP- & Carrier-JSON

Übersicht

Wo es in API-Antworten erscheint

Schema

Statuswerte

Lifecycle-Ereignistypen

Sitzungsübergreifende Übereinstimmungen

Beispiele

Approved – WhatsApp-OTP, Mobilfunkanbieter

Declined – VoIP-Nummer auf Sperrliste

Verwandte Themen

​Übersicht

​Wo es in API-Antworten erscheint

​Schema

​Statuswerte

​Lifecycle-Ereignistypen

​Sitzungsübergreifende Übereinstimmungen

​Beispiele

​Approved – WhatsApp-OTP, Mobilfunkanbieter

​Declined – VoIP-Nummer auf Sperrliste

​Verwandte Themen

Übersicht

Wo es in API-Antworten erscheint

Schema

Statuswerte

Lifecycle-Ereignistypen

Sitzungsübergreifende Übereinstimmungen

Beispiele

Approved – WhatsApp-OTP, Mobilfunkanbieter

Declined – VoIP-Nummer auf Sperrliste

Verwandte Themen