Zum Hauptinhalt springen
GET
Telefonnummern-Validierungs-API
Die Nutzung ist sehr einfach: Übermitteln Sie Ihren API-Schlüssel und eine Telefonnummer. Die API gibt zurück, ob die Nummer strukturell gültig ist, und bei gültigen Nummern normalisierte E.164-Formate sowie optionale Angaben wie Leitungstyp, Standorthinweise, Carrier-Daten, Zeitzonen und Erreichbarkeit, sofern verfügbar.
valid: true bedeutet, dass die Nummer den regionalen Formatregeln entspricht (Länge, Präfix, Syntax). Es bestätigt nicht, dass die Leitung aktiv ist, einem Teilnehmer zugewiesen oder erreichbar ist. Für den Live-Leitungsstatus benötigen Sie carrier lookup, was außerhalb dieses API liegt.

Erste Schritte

REST

Die Telefonnummern-Validierungs-API ist wie alle Cleariflow-APIs um REST herum aufgebaut. Sie verwendet vorhersehbare, ressourcenorientierte URLs und HTTP-Statuscodes zur Fehleranzeige.

HTTPS

Die Telefonnummern-Validierungs-API erfordert, dass alle Kommunikation mit TLS 1.2 oder höher gesichert ist.

API-Versionen

Alle Cleariflow-APIs sind versioniert. Die Telefonnummern-Validierungs-API befindet sich derzeit in Version 1.

Ihr API-Schlüssel

Ihr API-Schlüssel ist Ihr eindeutiger Authentifizierungsschlüssel für die Cleariflow Telefonnummern-Validierungs-API. Beachten Sie, dass jede Cleariflow-API einen eigenen API-Schlüssel hat — Sie benötigen also unterschiedliche Schlüssel für die Telefonnummern-Validierung und die E-Mail-Validierung. Zur Authentifizierung Ihrer Anfragen hängen Sie Ihren API-Schlüssel an die Basis-URL an.

Basis-URL

Was valid bedeutet

Fiktive US-555-Nummern und andere strukturell gültige, aber nicht zugewiesene Nummernbereiche können weiterhin valid: true zurückgeben. carrier und location werden hauptsächlich für US/CA-Nummern befüllt und sind anderswo oft leer.

Validierungs-Endpunkt

Die API benötigt Ihren eindeutigen API-Schlüssel und die zu prüfende Telefonnummer:
Gültige Antwort (phone=14155552671, country=US):
Ungültige Antwort (phone=123, country=US):

Anfrageparameter

api_key
String
erforderlich
Ihr eindeutiger API-Schlüssel. Beachten Sie, dass jeder Benutzer eindeutige API-Schlüssel für jede der Cleariflow-APIs hat — Ihr Phone Validation API-Schlüssel funktioniert beispielsweise nicht für die IP-Geolocation-API.
phone
String
erforderlich
Die zu validierende Telefonnummer (strukturelle Prüfung gemäß ).
country
String
Optionaler ISO 3166-1 alpha-2-Hinweis für nationale Nummern ohne führendes +. Beispielsweise hilft country=US beim Parsen von 4155552671. Nummern mit internationalem Präfix werden anhand ihrer Ländervorwahl geparst; der erkannte country.code in der Antwort kann von diesem Hinweis abweichen (z. B. GG für einige +44-Mobilbereiche).

Antwortparameter

Die API-Antwort wird in einem universellen und leichten JSON-Format zurückgegeben.
phone
String
Normalisierte E.164-Ziffern (ohne +), wenn valid true ist. Wenn valid false ist, nur Ziffern aus Ihrer Eingabe.
valid
Boolean
true, wenn die Nummer gemäß strukturell gültig ist. Dies ist keine Leitungsstatus- oder Teilnehmerverifizierung.
possible
Boolean
Nachsichtige Längenprüfung (). true, wenn Ziffern und Länge zu einer echten Nummer gehören könnten, auch wenn valid false ist.
invalid_reason
String
Vorhanden, wenn valid false ist. Einer von: not_a_number, possible, possible_local_only, invalid_country_code, too_short, invalid_length, too_long, unknown. Wird bei valid true weggelassen.
format
Object
international- und local-Formate. Leere Zeichenketten, wenn valid false ist.
format.international
String
E.164-Format mit führendem +. Leer, wenn valid false ist.
format.local
String
Nationales Format für die erkannte Region. Leer, wenn valid false ist.
country
Object
Erkanntes Land/Gebiet. Leere Felder, wenn valid false ist.
country.code
String
Zweistelliger ISO 3166-1 alpha-2-Code für die erkannte Region.
country.name
String
Englischer Anzeigename für country.code.
country.prefix
String
Internationale Ländervorwahl (z. B. +1).
location
String
Geocoding-Hinweis (Region, Bundesland/Provinz oder Stadt). Außerhalb von US/CA oft leer. Leer, wenn valid false ist.
type
String
Leitungstyp, wenn valid true ist: Landline, Mobile, Landline_or_Mobile, Toll_Free, Premium, Paging, Special oder Unknown. Immer Unknown, wenn valid false ist.
carrier
String
Betreibername, sofern verfügbar (meist US/CA). Andernfalls leere Zeichenkette, auch wenn valid false ist.
carrier_display
String
Sicherer Carrier-Name für die Anzeige an Endnutzer (wenn gültig und die Region keine Mobile Number Portability nutzt). Leer bei valid false oder wenn der Carrier nicht sicher angezeigt werden kann.
timezones
Array
Zeitzonen-IDs für die Nummer (z. B. America/New_York). Leeres Array bei valid true ohne Zuordnung; null bei valid false.
geographical
Boolean
Ob die Nummer einer geografischen Region zugeordnet ist. Immer false, wenn valid false ist.
internationally_dialable
Boolean
Ob die Nummer von außerhalb der Heimatregion gewählt werden kann. Immer false, wenn valid false ist.

Massen-Upload (CSV)

Best Practices beim Massen-Upload einer CSV-Datei:
  • Stellen Sie sicher, dass die erste Spalte die zu analysierenden Telefonnummern enthält.
  • Entfernen Sie leere Zeilen aus der Datei.
  • Fügen Sie nur eine Telefonnummer pro Zeile ein.
  • Die maximal zulässige Dateigröße beträgt 50.000 Zeilen.

Antwort- und Fehlercodes

Wenn eine Anfrage aus irgendeinem Grund fehlschlägt, wird ebenfalls ein Fehler im JSON-Format zurückgegeben. Die Fehler enthalten einen Fehlercode und eine Beschreibung — Details finden Sie unten.

Sonstige Hinweise

Hinweis zur nutzungsbasierten Abrechnung: Jede einzelne übermittelte Telefonnummer zählt als ein verwendeter Credit. Credits werden pro Anfrage gezählt, nicht pro erfolgreicher Antwort. Eine Anfrage mit der (ungültigen) Telefonnummer „kasj8929hs“ verbraucht also trotzdem 1 Credit.