> ## 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. # Telefoncode-Prüfung API: SMS-OTP validieren > POST /v3/phone/check/ validiert einen Telefon-OTP mit Carrier-Typ, virtueller Nummer und Wegwerfnummer-Erkennung. Abrechnung pro Nutzung, keine Mindestgebühren. ## Umgang mit Anbieterausfällen Ist der Telefonanbieter vorübergehend nicht erreichbar, gibt dieser Endpoint `502` mit einem stabilen, maschinenlesbaren Code zurück: ```json theme={null} { "detail": "The phone verification provider is temporarily unavailable.", "code": "phone_provider_unavailable" } ``` Behandeln Sie diese Antwort als für einen Wiederholungsversuch geeignet. Verwenden Sie einen kurzen Backoff und zeigen Sie dem Benutzer eine Meldung über die vorübergehende Nichtverfügbarkeit des Dienstes an, statt ihn aufzufordern, eine gültige Telefonnummer oder einen gültigen Code zu ändern. ## Add-on für Telefonanalysen Setzen Sie `enable_enrichment` auf `true`, um zusätzlich eine Telefonanalyse für die Nummer durchzuführen: einen Risiko-Score, den Leitungstyp, die Information, ob die Nummer kürzlich portiert wurde, und einen Vertrauensindex. Das Add-on wird zum Listenpreis von \$0.05 pro Anfrage abgerechnet, zusätzlich zum Preis der Prüfung. Die Anfrage gibt `403` zurück, wenn Ihr Guthaben dafür nicht ausreicht. Vier Felder bestimmen, was die Signale bewirken. Jedes davon ist `NO_ACTION` (der Standardwert) oder `DECLINE`, und jedes wird nur wirksam, wenn `enable_enrichment` auf `true` gesetzt ist. | Feld | Ablehnung, wenn | | - | - | | `phone_intelligence_score_action` | Der Risiko-Score über dem Schwellenwert liegt. | | `phone_type_risk_action` | Der Leitungstyp der Nummer ein hohes Risiko aufweist. | | `recent_port_action` | Die Nummer kürzlich zu einem anderen Anbieter portiert wurde. | | `low_phone_trust_action` | Der Vertrauensindex beim Schwellenwert liegt oder darunter. | Bei `NO_ACTION` wird das Signal trotzdem in `phone.phone_intelligence` zurückgegeben, sodass Sie Ihre eigene Regel anwenden können. ## OpenAPI ````yaml de/openapi-25.json POST /v3/phone/check/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API für Ausweisverifizierung. Authentifizierung über den x-api-key-Header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/phone/check/: post: tags: - Standalone APIs summary: Telefon-Code prüfen description: >- Verifizieren Sie das per [`POST /v3/phone/send/`](/de/standalone-apis/phone-send) zugestellte OTP und erhalten Sie das endgültige Verifizierungsergebnis sowie Telefoninformationen: Mobilfunkanbietername und Leitungstyp, Flags für virtuelle Nummern (VoIP) und Wegwerfnummern sowie die mehrfache Verwendung der Nummer über Ihre Sitzungen hinweg. **Wie die Prüfung die Verifizierung findet.** Der Abgleich erfolgt über Ihre Anwendung sowie die E.164-`phone_number` – `request_id` ist keine Eingabe. Es wird die neueste ausstehende Verifizierung geprüft, die innerhalb der letzten **5 Minuten** erstellt wurde. Gibt es keine (nie gesendet, bereits abgeschlossen oder älter als 5 Minuten), gibt der Endpoint `200` mit `status: "Expired or Not Found"` zurück. **Versuchsbudget.** Jede Verifizierung erlaubt **3 Code-Versuche**. Bei den ersten beiden falschen Codes wird `status: "Failed"` mit den verbleibenden Versuchen und `phone: null` zurückgegeben; der dritte falsche Code schließt die Verifizierung als `Declined` mit der Warnung `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` ab und gibt den vollständigen Telefonbericht zurück. **Ergebnisse.** `Approved` – korrekter Code und kein Ablehnungsrisiko. `Declined` – endgültig: Der Code war korrekt, aber es wurde ein Risiko für eine Ablehnung festgestellt (eine unten stehende `DECLINE`-Aktion, eine auf der Sperrliste stehende oder risikoreiche Nummer) oder das Versuchsbudget wurde aufgebraucht. `Failed` – falscher Code, verbleibende Versuche vorhanden. `Expired or Not Found` – nichts zu prüfen. Bei `Approved`/`Declined` entspricht die `request_id` der `request_id` des Sendevorgangs (die Sitzungs-ID) und `phone` enthält den vollständigen Bericht (`carrier`, `is_virtual`, `is_disposable`, `warnings`, `lifecycle`, `matches`); bei `Failed` und `Expired or Not Found` ist die `request_id` eine einmalige zufällige UUID. **Risiko-Aktionen.** `duplicated_phone_number_action`, `disposable_number_action` und `voip_number_action` bestimmen, was passiert, wenn das entsprechende Risiko bei einem korrekten Code erkannt wird: `DECLINE` ändert den Endstatus in `Declined`; `NO_ACTION` (Standard) erfasst das Risiko in `phone.warnings`, ohne den Status zu beeinflussen. **Abrechnung.** Prüfungen sind kostenlos – die Zustellung wird beim Senden abgerechnet (siehe [Preise für Telefonverifizierung](/de/getting-started/phone-verification-pricing)). **Sitzungspersistenz.** Eine abgeschlossene Prüfung aktualisiert die durch das Senden erstellte Sitzung (sichtbar in der Business Console, abfragbar über `GET /v3/session/{sessionId}/decision/`) und löst einen `status.updated`-Webhook aus. **Sandbox.** Sandbox-API-Schlüssel überspringen die gesamte Verarbeitung: Jeder wohlgeformte Code (4–8 Ziffern, einschließlich `123456`) gibt eine statische `Approved`-Payload mit einem vereinfachten flachen `phone`-Objekt zurück (`status`, `phone_number`, `country_code`, `carrier_name`, `line_type`, `flags`); fehlerhafte Eingaben geben weiterhin `400` zurück. Es wird nichts dauerhaft gespeichert. **Authentifizierung.** Senden Sie den API-Schlüssel Ihrer Anwendung im Header `x-api-key`. Fehlende oder ungültige Anmeldedaten geben `403` zurück (`{"detail": "You do not have permission to perform this action."}`) – diese API gibt niemals `401` zurück. **Rate-Limits.** Gemeinsames Schreibkontingent von 300 Anfragen/Min. pro API-Schlüssel sowie die vorgelagerte Anti-Missbrauchs-Obergrenze von 4 Versuchen pro Nummer und Stunde; das Überschreiten eines dieser Limits gibt `429` zurück. **Social-Media-Präsenz.** Setzen Sie `enable_social` auf `true`, um einen `phone_social`-Block hinzuzufügen: die Online-Plattformen, auf denen diese Nummer registriert ist, mit Anzahl pro Kategorie und allen verfügbaren Profildetails. `profiles_registered: 0` bedeutet, dass die Plattformen geprüft wurden und die Nummer auf keiner davon gefunden wurde – eine gültige, kostenpflichtige Antwort. Der Block fehlt, wenn das Add-on nicht angefragt wurde oder die Prüfung nicht abgeschlossen werden konnte; in diesem Fall wird er nicht in Rechnung gestellt. Bei der Abrechnung wird eine `phone_social`-Einheit pro Anfrage zusätzlich zum Preis dieses Endpoints berechnet. operationId: post_v3phone_check requestBody: required: true content: application/json: schema: type: object properties: phone_number: type: string maxLength: 20 description: >- Dieselbe Telefonnummer, die im zugehörigen Aufruf von [`POST /v3/phone/send/`](/de/standalone-apis/phone-send) verwendet wurde, im E.164-Format. Dadurch wird die Prüfung mit dem Versand verknüpft. example: '+14155552671' code: type: string minLength: 4 maxLength: 8 pattern: ^[0-9]{4,8}$ description: >- Das OTP, das der Endbenutzer erhalten hat. Muss aus 4–8 Ziffern bestehen – alles andere gibt `400` zurück, ohne einen Versuch zu verbrauchen. Ein wohlgeformter, aber falscher Code gibt `200` mit `status: "Failed"` zurück und verbraucht einen der 3 Versuche. example: '123456' duplicated_phone_number_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Was zu tun ist, wenn dieselbe Nummer bereits von einem anderen Benutzer (andere `vendor_data`) Ihrer Anwendung verwendet wurde. `DECLINE` ändert den finalen `status` zu `Declined`; `NO_ACTION` erfasst das Risiko in `phone.warnings` und befüllt `phone.matches`. disposable_number_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Was zu tun ist, wenn die Anbieterabfrage die Nummer als temporäre/Wegwerfnummer kennzeichnet (`phone.is_disposable`). `DECLINE` setzt den endgültigen `status` auf `Declined`; `NO_ACTION` erfasst das Risiko in `phone.warnings`. voip_number_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Was zu tun ist, wenn die Anbieterabfrage einen virtuellen Leitungstyp meldet — `voip`, `isp` oder `vpn` (`phone.is_virtual`). `DECLINE` setzt den endgültigen `status` auf `Declined`; `NO_ACTION` erfasst das Risiko in `phone.warnings`. enable_enrichment: type: boolean default: false description: >- Wenn `true`, wird zusätzlich eine Telefon-Intelligence für die Nummer ausgeführt: ein Risiko-Score, der Leitungstyp, ob sie kürzlich portiert wurde, und ein Vertrauensindex. Wird als eine `phone_intelligence_api`-Einheit pro Anfrage ($0.05 zum Listenpreis) zusätzlich zum eigenen Preis dieses Endpoints abgerechnet. Die Anfrage gibt `403` zurück, wenn Ihr Guthaben dies nicht decken kann. example: false phone_intelligence_score_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Aktion, wenn der Risiko-Score der Telefon-Intelligence über dem Schwellenwert liegt. `DECLINE` ändert den endgültigen `status` zu `Declined`; `NO_ACTION` erfasst das Signal, ohne abzulehnen. Wird nur wirksam, wenn `enable_enrichment` auf `true` gesetzt ist. phone_type_risk_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Aktion, wenn es sich bei der Nummer um einen risikoreichen Leitungstyp handelt. `DECLINE` ändert den endgültigen `status` zu `Declined`; `NO_ACTION` erfasst das Signal, ohne abzulehnen. Wird nur wirksam, wenn `enable_enrichment` auf `true` gesetzt ist. recent_port_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Aktion, wenn die Nummer kürzlich zu einem anderen Anbieter portiert wurde. `DECLINE` ändert den endgültigen `status` zu `Declined`; `NO_ACTION` erfasst das Signal, ohne abzulehnen. Wird nur wirksam, wenn `enable_enrichment` auf `true` gesetzt ist. low_phone_trust_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Aktion, wenn der Vertrauensindex der Telefon-Intelligence am oder unter dem Schwellenwert liegt. `DECLINE` ändert den endgültigen `status` zu `Declined`; `NO_ACTION` erfasst das Signal, ohne abzulehnen. Wird nur wirksam, wenn `enable_enrichment` auf `true` gesetzt ist. enable_social: type: boolean default: false description: >- Wenn true, wird auch der digitale Fußabdruck der Nummer ermittelt – die Messaging-, Social-, E-Commerce- und Berufs-Plattformen, auf denen sie registriert ist. Wird als eine `phone_social`-Einheit pro Anfrage zusätzlich zum regulären Preis dieses Endpoints abgerechnet. example: true phone_no_social_presence_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Aktion, wenn die Prüfung des digitalen Fußabdrucks (Social Footprint) ergibt, dass die Nummer auf keiner der abgedeckten Plattformen registriert ist. An diesem Endpoint werden nur NO_ACTION und DECLINE akzeptiert; REVIEW ist über den gleichnamigen Workflow-Konfigurationsschlüssel verfügbar. required: - phone_number - code examples: Default: summary: Alle Risiken erfassen, aber nie automatisch ablehnen value: phone_number: '+14155552671' code: '123456' Strict risk policy: summary: VoIP- und Wegwerf-Telefonnummern automatisch ablehnen value: phone_number: '+14155552671' code: '123456' voip_number_action: DECLINE disposable_number_action: DECLINE responses: '200': description: >- Prüfung abgeschlossen – falsche Codes und fehlende Verifizierungen geben ebenfalls `200` zurück; prüfen Sie `status`, nicht den HTTP-Code. `phone` ist nur bei abgeschlossenen Ergebnissen (`Approved`/`Declined`) ausgefüllt, `null` bei `Failed` und fehlt bei `Expired or Not Found`. content: application/json: schema: $ref: '#/components/schemas/PhoneVerificationCheckResponse' examples: Approved: summary: >- Korrekter Code – vollständiger Telefonbericht mit Mobilfunkanbieter, Lebenszyklus und Übereinstimmungen value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Approved message: The verification code is correct. phone: status: Approved phone_number_prefix: '+1' phone_number: '4155552671' full_number: '+14155552671' country_code: US country_name: United States carrier: name: AT&T type: mobile is_disposable: false is_virtual: false verification_method: whatsapp verification_attempts: 1 verified_at: '2026-06-12T01:24:47.311323Z' warnings: [] lifecycle: - type: PHONE_VERIFICATION_MESSAGE_SENT timestamp: '2026-06-12T01:23:39.580554+00:00' details: status: Success reason: null channel: whatsapp actual_channel: whatsapp fee: 0.0509 - type: PHONE_DELIVERY_DELIVERED timestamp: '2026-06-12T01:23:43.118220+00:00' details: channel: whatsapp status: delivered fee: 0 - type: VALID_CODE_ENTERED timestamp: '2026-06-12T01:24:47.311201+00:00' details: code_tried: '123456' status: Approved fee: 0 - type: PHONE_VERIFICATION_APPROVED timestamp: '2026-06-12T01:24:47.384292+00:00' details: null fee: 0 matches: [] vendor_data: user-1234 metadata: null created_at: '2026-06-12T01:24:47.401719+00:00' Failed (attempts remaining): summary: >- Falscher Code – der Benutzer kann es erneut versuchen; request_id ist hier eine einmalige UUID value: request_id: 11111111-2222-3333-4444-555555555555 status: Failed message: 'The verification code is incorrect. Attempts remaining: 2' phone: null vendor_data: user-1234 metadata: null created_at: '2026-06-12T01:24:21.512340+00:00' Declined (max attempts): summary: >- Dritter falscher Code — Verifizierung als abgelehnt abgeschlossen value: request_id: e39cb057-92fc-4b59-b84e-02fec29a0f24 status: Declined message: >- The verification code is incorrect. Maximum attempts reached. phone: status: Declined phone_number_prefix: '+1' phone_number: '4155552671' full_number: '+14155552671' country_code: US country_name: United States carrier: name: AT&T type: mobile is_disposable: false is_virtual: false verification_method: whatsapp verification_attempts: 1 verified_at: null warnings: - feature: PHONE risk: VERIFICATION_CODE_ATTEMPTS_EXCEEDED additional_data: null log_type: error short_description: Verification code attempts exceeded long_description: >- The system detected that the phone number has exceeded the maximum number of verification code attempts. lifecycle: - type: PHONE_VERIFICATION_MESSAGE_SENT timestamp: '2026-06-12T01:23:39.580554+00:00' details: status: Success reason: null channel: whatsapp actual_channel: whatsapp fee: 0.0509 - type: INVALID_CODE_ENTERED timestamp: '2026-06-12T01:24:01.118220+00:00' details: code_tried: '111111' status: Failed fee: 0 - type: INVALID_CODE_ENTERED timestamp: '2026-06-12T01:24:21.512340+00:00' details: code_tried: '222222' status: Failed fee: 0 - type: INVALID_CODE_ENTERED timestamp: '2026-06-12T01:24:47.311201+00:00' details: code_tried: '333333' status: Failed fee: 0 - type: PHONE_VERIFICATION_DECLINED timestamp: '2026-06-12T01:24:47.384292+00:00' details: reason: VERIFICATION_CODE_ATTEMPTS_EXCEEDED fee: 0 matches: [] vendor_data: user-1234 metadata: null created_at: '2026-06-12T01:24:47.401719+00:00' Declined (risk policy): summary: >- Korrekter Code, aber der Anschluss ist VoIP und voip_number_action=DECLINE value: request_id: 7f1c9d2e-44a1-4b6e-9a3e-5b8e6f1c2d3a status: Declined message: The verification code is correct. phone: status: Declined phone_number_prefix: '+1' phone_number: '5005550006' full_number: '+15005550006' country_code: US country_name: United States carrier: name: CLEC LLC type: voip is_disposable: false is_virtual: true verification_method: sms verification_attempts: 1 verified_at: '2026-06-12T01:24:47.311323Z' warnings: - feature: PHONE risk: VOIP_NUMBER_DETECTED additional_data: null log_type: error short_description: VoIP number detected long_description: >- The system detected that the phone number is a VoIP number, which is not allowed. lifecycle: - type: PHONE_VERIFICATION_MESSAGE_SENT timestamp: '2026-06-12T01:23:39.580554+00:00' details: status: Success reason: null channel: whatsapp actual_channel: sms fee: 0.0509 - type: VALID_CODE_ENTERED timestamp: '2026-06-12T01:24:47.311201+00:00' details: code_tried: '123456' status: Approved fee: 0 - type: PHONE_VERIFICATION_DECLINED timestamp: '2026-06-12T01:24:47.384292+00:00' details: reason: VOIP_NUMBER_DETECTED fee: 0 matches: [] vendor_data: user-1234 metadata: null created_at: '2026-06-12T01:24:47.401719+00:00' Expired or Not Found: summary: >- Keine ausstehende Verifizierung für diese Nummer in den letzten 5 Minuten value: request_id: 69cc35c6-280a-47a6-ab8c-4f32abc02ed0 status: Expired or Not Found message: No pending phone verification found in the last 5 minutes. vendor_data: null metadata: null created_at: '2026-06-12T01:24:47.311323+00:00' '400': description: >- Validierungsfehler – DRFs Feldfehler-Envelope: ein Array von Meldungen pro fehlerhaftem Feld. content: application/json: examples: Invalid code format: summary: '`code` besteht nicht aus 4–8 numerischen Ziffern' value: code: - Invalid code format. Enter 4 to 8 numeric digits. Invalid phone number: summary: '`phone_number` ist keine gültige E.164-Nummer' value: phone_number: - Invalid phone number provided. Invalid action: summary: Risikoaktionen akzeptieren nur NO_ACTION oder DECLINE value: voip_number_action: - '"REVIEW" is not a valid choice.' '403': description: >- Zugriff verweigert. Wird zurückgegeben, wenn der Header `x-api-key` fehlt; ein falscher, widerrufener oder abgelaufener Schlüssel gibt `401` zurück. Prüfungen sind kostenlos, daher erfolgt hier keine Credit-Prüfung. content: application/json: examples: Missing or invalid API key: summary: >- Kein `x-api-key`-Header, oder der Schlüssel ist ungültig/widerrufen value: detail: You do not have permission to perform this action. '429': description: >- Rate-Limit überschritten. POST/PATCH/DELETE-Endpoints teilen sich ein Budget von 300 Schreibanfragen pro Minute pro API-Schlüssel (Transaktionserstellungen und Ereignis-Ingestion haben ein separates Budget von 600). Zusätzlich gilt vorgelagert eine Obergrenze zum Missbrauchsschutz von 4 Verifizierungsversuchen pro Telefonnummer pro Stunde. Die Antwort enthält die Header `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` und `Retry-After`. Hinweis: Die Header `X-RateLimit-*`/`Retry-After` begleiten nur den 429-Fehler des Schreiblimits von 300/Min; der 429-Fehler der Obergrenze pro Nummer enthält keine Rate-Limit-Header. content: application/json: examples: Per-number cap: summary: >- Mehr als 4 Verifizierungsversuche für dieselbe Nummer in der letzten Stunde value: detail: >- Maximum verification attempts reached for this phone number. Only 4 authentication attempts are allowed per hour. Try again later or use a different number. Write rate limit exceeded: summary: Mehr als 300 Schreibanfragen in der aktuellen Minute value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '500': description: >- Unerwarteter Fehler bei der vorgelagerten Verifizierung des Codes, der kein bekannter Anbieterausfall ist. Kann sicher wiederholt werden; das Versuchsbudget wird nur durch abgeschlossene Prüfungen verbraucht. content: application/json: examples: Provider error: summary: Code-Verifizierung konnte nicht abgeschlossen werden value: detail: Error checking phone verification schema: type: object properties: detail: type: string '502': description: >- Der Telefonverifizierungsanbieter ist vorübergehend nicht verfügbar – eine 5xx-Antwort, ein Timeout oder ein Verbindungsfehler, der die integrierten Wiederholungsversuche überdauert hat. Kann gefahrlos wiederholt werden; das Versuchskontingent wird nicht verbraucht. content: application/json: examples: Provider outage: summary: Der Anbieter hat die Prüfungsanfrage nicht beantwortet value: detail: >- Phone verification is temporarily unavailable. Please try again shortly. code: phone_provider_unavailable schema: type: object properties: detail: type: string code: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/phone/check/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "phone_number": "+14155552671", "code": "123456", "voip_number_action": "DECLINE" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.phone.check_code( phone_number="+14155552671", code="123456", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.phone.checkCode({ phone_number: "+14155552671", code: "123456", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.CheckCode(ctx, didit.PhoneCheckCodeParams{\n\tPhoneNumber: \"+14155552671\",\n\tCode: \"123456\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: |- import me.didit.Didit; import me.didit.types.PhoneCheckCodeParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.phone().checkCode(PhoneCheckCodeParams.builder() .phoneNumber("+14155552671") .code("123456") .build()); System.out.println(result); - lang: php label: PHP source: |- phone->checkCode([ 'phone_number' => '+14155552671', 'code' => '123456', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.phone.check_code( phone_number: "+14155552671", code: "123456" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Phone.CheckCodeAsync(new PhoneCheckCodeParams { PhoneNumber = "+14155552671", Code = "123456", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: PhoneVerificationCheckResponse: type: object properties: request_id: type: string format: uuid description: >- Bei `Approved`/`Declined`: die Sitzungs-ID der zugeordneten Verifizierung – identisch mit der von `POST /v3/phone/send/` zurückgegebenen `request_id`. Bei `Failed` und `Expired or Not Found`: eine zufällige einmalige UUID, die später nicht nachgeschlagen werden kann. status: type: string enum: - Approved - Declined - Failed - Expired or Not Found description: >- `Approved` — korrekter Code, kein zur Ablehnung führendes Risiko. `Declined` — endgültig: Ein zur Ablehnung führendes Risiko lag vor oder das Kontingent an Versuchen (3) wurde aufgebraucht. `Failed` — falscher Code, verbleibende Versuche vorhanden. `Expired or Not Found` — keine ausstehende Verifizierung für diese Nummer in den letzten 5 Minuten. message: type: string description: >- Lesbare Erklärung des Ergebnisses, einschließlich der verbleibenden Anzahl von Versuchen nach einem falschen Code. phone: type: object nullable: true description: >- Vollständiger Telefonbericht. Nur bei endgültigen Ergebnissen vorhanden (nicht null) (`Approved`/`Declined`); `null` bei `Failed` und nicht vorhanden bei `Expired or Not Found`. properties: status: type: string enum: - Approved - Declined - In Review - Not Finished - Expired description: >- Endgültiger Status der Telefonverifizierung. Entspricht dem übergeordneten `status` für abgeschlossene Prüfungen. phone_number_prefix: type: string description: Ländervorwahl mit vorangestelltem `+` (z. B. `+1`). example: '+1' phone_number: type: string description: Nationale Rufnummer ohne Ländervorwahl. example: '4155552671' full_number: type: string description: Vollständige Nummer im E.164-Format. example: '+14155552671' country_code: type: string nullable: true description: ISO 3166-1-Alpha-2-Land der Nummer. example: US country_name: type: string description: Vollständiger Ländername, abgeleitet aus `country_code`. example: United States carrier: type: object description: >- Netzwerk, über das die Nummer aktuell betrieben wird, aus der beim Abschluss durchgeführten Netzbetreiberabfrage. properties: name: type: string description: >- Name des Mobilfunkanbieters. Leere Zeichenkette, wenn die Abfrage ihn nicht identifizieren konnte. type: type: string description: >- Durch die Abfrage gemeldeter Leitungstyp: `mobile`, `fixed_line`, `voip`, `isp`, `vpn`, `toll_free`, `premium_rate`, `pager`, `payphone`, `satellite`, `service`, `shared_cost`, `short_codes_commercial`, `calling_cards`, `local_rate`, `universal_access`, `voice_mail`, `other` oder `unknown`. is_disposable: type: boolean description: >- `true`, wenn die Nummer zu einem temporären/Burner-Nummern-Dienst gehört. is_virtual: type: boolean description: >- `true`, wenn der Leitungstyp virtuell ist (`voip`, `isp` oder `vpn`). verification_method: type: string description: >- Kanal, der das OTP nach Bestätigung der Zustellung tatsächlich zugestellt hat (z. B. `whatsapp`, `sms`); bis dahin der angeforderte Kanal. verification_attempts: type: integer description: >- Anzahl der OTP-Sendungen für diese Verifizierung (1, oder 2 nach einem Wiederholungsversuch). verified_at: type: string format: date-time nullable: true description: >- Wann der korrekte Code eingegeben wurde. `null`, wenn die Verifizierung nie genehmigt wurde. warnings: type: array description: >- Während der Verifizierung erfasste Risikowarnungen (Duplikat, Einwegnummer, VoIP, Versuche überschritten, Sperrliste usw.). Leeres Array, wenn keine vorhanden sind. items: type: object properties: feature: type: string description: Funktion, die die Warnung erzeugt hat. Hier immer `PHONE`. risk: type: string description: Maschinenlesbarer Risiko-Code. additional_data: type: object nullable: true description: >- Risikospezifischer Kontext (z. B. die ID der duplizierten Sitzung bei Duplikatsrisiken). `null`, wenn das Risiko keine zusätzlichen Daten enthält. log_type: type: string enum: - error - warning - information description: >- Schweregrad. `error`-Risiken führen zur Ablehnung der Verifizierung, `warning` markiert sie zur Prüfung, `information` wird erfasst, ohne den Status zu beeinflussen. short_description: type: string description: >- Für Menschen lesbare einzeilige Zusammenfassung des Risikos. long_description: type: string description: Lesbare Erklärung des Risikos. lifecycle: type: array description: >- Chronologischer Audit-Trail der Verifizierung. Der Ereignis-`type` ist einer von `PHONE_VERIFICATION_MESSAGE_SENT`, `PHONE_VERIFICATION_RETRY_MESSAGE_SENT`, `PHONE_VERIFICATION_BLOCKED`, `PHONE_DELIVERY_DELIVERED`, `PHONE_DELIVERY_UNDELIVERABLE`, `VALID_CODE_ENTERED`, `INVALID_CODE_ENTERED`, `PHONE_VERIFICATION_APPROVED`, `PHONE_VERIFICATION_DECLINED`, `PHONE_VERIFICATION_IN_REVIEW`, `PHONE_VERIFICATION_EXPIRED`. items: type: object properties: type: type: string description: Ereignistyp. timestamp: type: string format: date-time description: Wann das Ereignis stattgefunden hat. details: type: object nullable: true description: >- Ereignisspezifische Payload. Sende-Ereignisse: `{status, reason, channel, actual_channel}` (`actual_channel` wird ausgefüllt, sobald die Zustellung bestätigt ist). Zustellungs-Ereignisse: `{channel, status}`. Code-Eingabe-Ereignisse: `{code_tried, status}`. Finale Status-Ereignisse: `null` oder `{reason}`, wenn abgelehnt oder in Prüfung. fee: type: number description: >- Für dieses Ereignis abgerechneter USD-Betrag. Nur bei Sendeereignissen ungleich null (der Zustellpreis); 0 bei Code-Eingaben, Zustellbestätigungen und Statusereignissen. matches: type: array description: >- Andere Sitzungen Ihrer Anwendung (KYC, KYB oder API), bei denen dieselbe Telefonnummer von einem anderen Benutzer (anderes `vendor_data`) verwendet wurde. Bis zu 5 Einträge, ein synthetischer Sperrlistentreffer für einen Listeneintrag an erster Stelle, sofern vorhanden (sitzungsbasierte Treffer behalten die Abfragereihenfolge bei). Leeres Array, wenn keine Treffer vorliegen. items: type: object properties: session_id: type: string format: uuid description: >- Sitzungs-ID der anderen Verifizierung, die diese Telefonnummer verwendet hat. session_number: type: integer description: Benutzerfreundliche fortlaufende Nummer dieser Sitzung. vendor_data: type: string nullable: true description: '`vendor_data` dieser Sitzung.' verification_date: type: string description: >- Wann diese Sitzung erstellt wurde (`YYYY-MM-DDTHH:MM:SSZ`). phone_number: type: string description: Die übereinstimmende Telefonnummer. status: type: string description: >- Status dieser Sitzung (z. B. `Approved`, `Declined`, `In Progress`). is_blocklisted: type: boolean description: >- Gibt an, ob die Telefonnummer auf der Sperrliste Ihrer Anwendung steht. api_service: type: string nullable: true description: >- Für Sitzungen vom API-Typ: die eigenständige API, die sie erstellt hat (z. B. `PHONE_VERIFICATION`); `null` für reguläre Verifizierungssitzungen. source: type: string description: >- Wo die Übereinstimmung gefunden wurde. Normalerweise `session`; ein Sperrlisten-Treffer über einen Organisationslisteneintrag stellt eine synthetische Übereinstimmung mit `source: "list_entry"` und Nullwerten für `session_id`/`session_number` voran. phone_social: $ref: '#/components/schemas/PhoneSocialFootprint' phone_intelligence: allOf: - $ref: '#/components/schemas/PhoneIntelligence' description: >- Telefon-Intelligence-Signale. Nur vorhanden, wenn bei der Prüfung `enable_enrichment` auf `true` gesetzt war. vendor_data: type: string nullable: true description: >- `vendor_data` der Sitzung der übereinstimmenden Verifizierung. `null` bei `Expired or Not Found`. metadata: type: object nullable: true description: >- `metadata` der Sitzung der zugeordneten Verifizierung. `null` bei `Expired or Not Found`. created_at: type: string format: date-time description: Zeitstempel dieser Prüfungsantwort. PhoneSocialFootprint: type: object nullable: true description: >- Social Footprint der Telefonnummer: die Online-Plattformen, auf denen sie registriert ist. Nur vorhanden, wenn `enable_social` gesetzt war und die Prüfung abgeschlossen wurde. Jeder Zähler kann null sein, wenn dafür keine Daten zurückgegeben wurden. `profiles_registered: 0` bedeutet, dass die Plattformen geprüft wurden und die Telefonnummer auf keiner davon gefunden wurde – eine gültige, abrechenbare Antwort und ein häufiges Signal für eine synthetische Identität. properties: profiles_registered: type: integer nullable: true description: >- Plattformen, bei denen die Telefonnummer nachweislich registriert ist. example: 5 profiles_checked: type: integer nullable: true description: Auf Registrierung geprüfte Plattformen. example: 14 names_found: type: integer nullable: true description: Plattformen, die einen zugehörigen Namen zurückgegeben haben. example: 0 photos_found: type: integer nullable: true description: Plattformen, die ein Profilfoto zurückgegeben haben. example: 0 communication_breadth: type: integer nullable: true description: Kommunikationsplattformen mit erkannter Präsenz. example: 2 digital_footprint_diversity: type: integer nullable: true description: Unterschiedliche Plattformkategorien mit erkannter Präsenz. example: 5 digital_sophistication_index: type: integer nullable: true description: Zusammengesetzter Indikator für digitale Reife, 0-10. example: 5 engagement_depth_index: type: integer nullable: true description: Indikator für die Profilreichhaltigkeit, 0–10. example: 3 subscription_affordability_index: type: integer nullable: true description: Mix aus kostenlosen vs. kostenpflichtigen Plattformen, 0-10. example: 2 free_platforms: type: integer nullable: true description: Registrierungen auf kostenlosen Plattformen. example: 4 full_paid_platforms: type: integer nullable: true description: Registrierungen auf rein kostenpflichtigen Plattformen. example: 0 partial_paid_platforms: type: integer nullable: true description: Registrierungen auf Freemium-Plattformen. example: 1 whatsapp_profile_completeness: type: string nullable: true enum: - Basic - Partial - Complete - Not Present - null description: >- Vollständigkeit des WhatsApp-Profils. Nur für Telefonnummern; null für E-Mail-Adressen. example: Partial registered_platforms: type: array description: Plattformen, bei denen eine Registrierung bestätigt ist. items: $ref: '#/components/schemas/SocialFootprintPlatform' not_registered_platforms: type: array description: Geprüfte Plattformen mit negativem Ergebnis. items: $ref: '#/components/schemas/SocialFootprintPlatform' categories: type: object description: Anzahl der Registrierungen und Verhältnis pro Plattformkategorie. additionalProperties: $ref: '#/components/schemas/SocialFootprintCategorySummary' profiles: type: object description: >- Profildetails pro Plattform, geschlüsselt nach Plattform, sofern die Plattform diese bereitstellt. additionalProperties: $ref: '#/components/schemas/SocialFootprintProfile' PhoneIntelligence: type: object description: >- Normalisierter Telefon-Intelligence-Block. Nur vorhanden, wenn das Intelligence-Add-on für diese Abfrage ausgeführt wurde; falls vorhanden, wird er auch unter dem `enrichment`-Alias mit identischen Werten bereitgestellt. properties: score: type: number nullable: true description: Normalisierter Risiko-Score von 0–100. Höher ist riskanter. phone_type_risk: type: string nullable: true description: '`Low`, `Medium` oder `High`, abgeleitet aus dem Score.' phone_trust_index: type: number nullable: true description: Kehrwert des Werts, für Dashboards, die höhere Werte bevorzugen. network_stability_index: type: number nullable: true description: Stabilität des Leitungsnetzwerks. is_disposable: type: boolean nullable: true description: >- `true`, wenn die Nummer wie eine Wegwerf- oder virtuelle Nummer aussieht. is_ported: type: boolean nullable: true description: '`true`, wenn die Nummer den Mobilfunkanbieter gewechselt hat.' is_recently_ported: type: boolean nullable: true description: '`true`, wenn die Portierung kürzlich erfolgt ist.' carrier_type: type: string nullable: true description: >- Durch die Abfrage gemeldete Leitungsklassifizierung (z. B. `mobile`). reason_codes: type: array items: type: object properties: code: type: string description: >- Stabiler Didit-Identifikator des Signals, zum Beispiel `IR-5AC67A32`. Opak: danach gruppieren und filtern, nicht parsen. value: nullable: true description: >- Für ein Risiko-Flag (beispielsweise `voip`, `leaked`, `disposable`, `spam_trap`): dessen Wert: ein boolescher Wert, eine Stufe oder ein Datum. Null für einen bewerteten Grundcode. direction: type: string enum: - risk - trust description: >- Gibt an, ob das Signal das Risiko erhöht oder das Vertrauen gestärkt hat. message: type: string description: Lesbare Erklärung des Signals, auf Englisch. impact_level: type: string nullable: true description: >- Wie stark das Signal den Score beeinflusst hat, zum Beispiel `low`, `medium` oder `high`. description: >- Signale, die den Score erklären, jeweils mit einem stabilen Didit-Code, einer Richtung, einer Nachricht und einer Auswirkungsstufe. Im Laufe der Zeit können neue Codes hinzukommen; weisen Sie unbekannte Codes daher nicht ab. SocialFootprintPlatform: type: object properties: platform: type: string description: Plattform-Identifikator. example: whatsapp category: type: string description: >- Plattformkategorie, z. B. MESSAGING, SOCIAL_MEDIA, ECOMMERCE, PROFESSIONAL, EMAIL_PROVIDER. example: MESSAGING scope: type: string enum: - global - local description: >- `global` für weltweite Plattformen, `local` für regionsspezifische Plattformen. example: global SocialFootprintCategorySummary: type: object properties: registered: type: integer nullable: true description: >- Plattformen in dieser Kategorie, bei denen eine Registrierung bestätigt ist. example: 2 ratio: type: number format: float nullable: true description: >- Anteil der geprüften Plattformen der Kategorie mit einer Registrierung, 0.0-1.0. example: 0.6667 SocialFootprintProfile: type: object properties: name: type: string nullable: true description: Profilname, sofern die Plattform diesen bereitstellt. photo: type: string nullable: true description: Profilfoto-URL, sofern die Plattform diese bereitstellt. about: type: string nullable: true description: Profil-Info-/Bio-Text, sofern die Plattform diesen bereitstellt. privacy_status: type: string nullable: true enum: - PUBLIC - PRIVATE - null description: Profilsichtbarkeit, sofern die Plattform diese bereitstellt. business_account: type: boolean nullable: true description: >- Gibt an, ob das Profil ein Geschäftskonto ist, sofern die Plattform dies bereitstellt. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Der API-Schlüssel Ihrer Anwendung, aus Entwickler -> API-Schlüssel in der Business Console. Der Primärschlüssel hat Vollzugriff. Ein benannter Schlüssel kann im Geltungsbereich eingeschränkt werden: keine, Lese- oder Schreibberechtigung pro Ressource, beschränkt auf bestimmte Workflows oder genehmigte Sitzungen, auf eine Liste von IP-Adressen und auf ein Ablaufdatum. 401 bedeutet, dass der Schlüssel falsch, widerrufen oder abgelaufen ist; 403 bedeutet, dass kein Schlüssel gesendet wurde, der Schlüssel keinen Zugriff auf diese Ressource oder Aktion hat oder die Anfrage von einer Adresse außerhalb seiner IP-Liste stammte; 404 bei einer Sitzungsroute bedeutet, dass die Sitzung außerhalb der Workflows oder Status des Schlüssels liegt. Ein Schlüssel ohne Medienzugriff erhält Bild-, Video- und PDF-URLs als null, und ein Schlüssel ohne Schreibberechtigung für Sitzungen erhält Sitzungslinks und Token als null. Siehe https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.