Telefonnummern-Validierungs-API

GET

curl --request GET \
  --url https://phonevalidation.cleariflow.com/v1

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://phonevalidation.cleariflow.com/v1",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://phonevalidation.cleariflow.com/v1"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://phonevalidation.cleariflow.com/v1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "phone": "14155552671",
  "valid": true,
  "possible": 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": "",
  "carrier_display": "",
  "timezones": ["America/Los_Angeles"],
  "geographical": true,
  "internationally_dialable": true
}

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

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

Was `valid` bedeutet

`valid`	Bedeutung
`true`	Die Nummer ist für ihre erkannte Region strukturell gültig.
`false`	Die Nummer konnte nicht geparst werden oder entspricht nicht den regionalen Formatregeln. `format`, `country`, `location`, `type`, `carrier`, `carrier_display`, `timezones`, `geographical` und `internationally_dialable` sind immer leer oder false; `possible` und `invalid_reason` werden weiterhin befüllt, wenn die Eingabe analysiert werden konnte. `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 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:

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,
  "possible": 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": "",
  "carrier_display": "",
  "timezones": ["America/Los_Angeles"],
  "geographical": true,
  "internationally_dialable": true
}

Ungültige Antwort (phone=123, country=US):

{
  "phone": "123",
  "valid": false,
  "possible": false,
  "invalid_reason": "too_short",
  "format": {
    "international": "",
    "local": ""
  },
  "country": {
    "code": "",
    "name": "",
    "prefix": ""
  },
  "location": "",
  "type": "Unknown",
  "carrier": "",
  "carrier_display": "",
  "timezones": null,
  "geographical": false,
  "internationally_dialable": false
}

Anfrageparameter

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.

String

erforderlich

Die zu validierende Telefonnummer (strukturelle Prüfung gemäß ).

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.

String

Normalisierte E.164-Ziffern (ohne +), wenn valid true ist. Wenn valid false ist, nur Ziffern aus Ihrer Eingabe.

Boolean

true, wenn die Nummer gemäß strukturell gültig ist. Dies ist keine Leitungsstatus- oder Teilnehmerverifizierung.

Boolean

Nachsichtige Längenprüfung (). true, wenn Ziffern und Länge zu einer echten Nummer gehören könnten, auch wenn valid false ist.

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.

Object

international- und local-Formate. Leere Zeichenketten, wenn valid false ist.

String

E.164-Format mit führendem +. Leer, wenn valid false ist.

String

Nationales Format für die erkannte Region. Leer, wenn valid false ist.

Object

Erkanntes Land/Gebiet. Leere Felder, wenn valid false ist.

String

Zweistelliger ISO 3166-1 alpha-2-Code für die erkannte Region.

String

Englischer Anzeigename für country.code.

String

Internationale Ländervorwahl (z. B. +1).

String

Geocoding-Hinweis (Region, Bundesland/Provinz oder Stadt). Außerhalb von US/CA oft leer. Leer, wenn valid false ist.

String

Leitungstyp, wenn valid true ist: Landline, Mobile, Landline_or_Mobile, Toll_Free, Premium, Paging, Special oder Unknown. Immer Unknown, wenn valid false ist.

String

Betreibername, sofern verfügbar (meist US/CA). Andernfalls leere Zeichenkette, auch wenn valid false ist.

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.

Array

Zeitzonen-IDs für die Nummer (z. B. America/New_York). Leeres Array bei valid true ohne Zuordnung; null bei valid false.

Boolean

Ob die Nummer einer geografischen Region zugeordnet ist. Immer false, wenn valid false ist.

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.

Code	Type	Details
200	OK	Alles hat wie erwartet funktioniert.
400	Bad request	Ungültige Anfrage.
401	Unauthorized	Die Anfrage war nicht akzeptabel. Typischerweise wegen fehlendem oder falschem API-Schlüssel.
422	Quota reached	Die Anfrage wurde wegen unzureichender API-Credits abgebrochen. (Kostenlose Tarife)
429	Too many requests	Die 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.
500	Internal server error	Die Anfrage konnte wegen eines Serverfehlers nicht abgeschlossen werden.
503	Service unavailable	Der 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.

Telefonnummern-Validierungs-API

curl --request GET \
  --url https://phonevalidation.cleariflow.com/v1

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://phonevalidation.cleariflow.com/v1",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://phonevalidation.cleariflow.com/v1"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://phonevalidation.cleariflow.com/v1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "phone": "14155552671",
  "valid": true,
  "possible": 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": "",
  "carrier_display": "",
  "timezones": ["America/Los_Angeles"],
  "geographical": true,
  "internationally_dialable": true
}

Validierung

Abfrage

Erstellung

Telefonnummern-Validierungs-API

Erste Schritte

REST

HTTPS

API-Versionen

Ihr API-Schlüssel

Basis-URL

Was `valid` bedeutet

Validierungs-Endpunkt

Anfrageparameter

Antwortparameter

Massen-Upload (CSV)

Antwort- und Fehlercodes

Sonstige Hinweise

​Erste Schritte

​REST

​HTTPS

​API-Versionen

​Ihr API-Schlüssel

​Basis-URL

​Was valid bedeutet

​Validierungs-Endpunkt

​Anfrageparameter

​Antwortparameter

​Massen-Upload (CSV)

​Antwort- und Fehlercodes

​Sonstige Hinweise

Erste Schritte

REST

HTTPS

API-Versionen

Ihr API-Schlüssel

Basis-URL

Was `valid` bedeutet

Validierungs-Endpunkt

Anfrageparameter

Antwortparameter

Massen-Upload (CSV)

Antwort- und Fehlercodes

Sonstige Hinweise