Zum Hauptinhalt springen
GET
/
v1
Telefonnummern-Validierungs-API
curl --request GET \
  --url https://phonevalidation.cleariflow.com/v1
{
  "phone": "14155552671",
  "valid": true,
  "format": {
    "international": "+14155552671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": ""
}
Die Nutzung ist sehr einfach: Sie übermitteln Ihren API-Schlüssel und eine Telefonnummer. Die API gibt zurück, ob die Nummer strukturell gültig ist (gemäß Google libphonenumber), und bei gültigen Nummern normalisierte E.164-Formate sowie optionale Metadaten wie Leitungstyp, Geocoding-Hinweise und Betreiberdaten, 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 HLR/SMS 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

https://phonevalidation.cleariflow.com/v1/

​
Was valid bedeutet

validBedeutung
trueDie Nummer ist für ihre erkannte Region strukturell gültig (libphonenumber IsValidNumber).
falseDie Nummer konnte nicht geparst werden oder verstößt gegen regionale Formatregeln. format, country, location, type und carrier sind immer leer; phone enthält nur Ziffern aus Ihrer Eingabe.
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 aus US/CA-Metadaten befüllt und sind anderswo oft leer.

​
Validierungs-Endpunkt

Die API benötigt Ihren eindeutigen API-Schlüssel und die zu prüfende Telefonnummer: 
https://phonevalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& phone = 14155552671
& country = US
Gültige Antwort (phone=14155552671, country=US): 
{
  "phone": "14155552671",
  "valid": true,
  "format": {
    "international": "+14155552671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": ""
}
Ungültige Antwort (phone=123, country=US): 
{
  "phone": "123",
  "valid": false,
  "format": {
    "international": "",
    "local": ""
  },
  "country": {
    "code": "",
    "name": "",
    "prefix": ""
  },
  "location": "",
  "type": "Unknown",
  "carrier": ""
}

​
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äß libphonenumber).
​
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äß libphonenumber strukturell gültig ist. Dies ist keine Leitungsstatus- oder Teilnehmerverifizierung.
​
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 aus libphonenumber-Metadaten (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 aus libphonenumber-Metadaten, sofern verfügbar (meist US/CA). Andernfalls leere Zeichenkette, auch 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.
CodeTypeDetails
200OKAlles hat wie erwartet funktioniert.
400Bad requestUngültige Anfrage.
401UnauthorizedDie Anfrage war nicht akzeptabel. Typischerweise wegen fehlendem oder falschem API-Schlüssel.
422Quota reachedDie Anfrage wurde wegen unzureichender API-Credits abgebrochen. (Kostenlose Tarife)
429Too many requestsDie Anfrage wurde abgebrochen, weil die zulässige Anzahl an Anfragen pro Sekunde erreicht wurde. Bei kostenlosen Tarifen ist dies auf 1 Anfrage pro Sekunde begrenzt.
500Internal server errorDie Anfrage konnte wegen eines Serverfehlers nicht abgeschlossen werden.
503Service unavailableDer Server war nicht verfügbar.

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