Vai al contenuto principale
GET
/
v1
API di validazione numeri di telefono
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": ""
}
È molto semplice da usare: inviate la chiave API e un numero di telefono. L’API restituisce se il numero è strutturalmente valido (secondo Google libphonenumber) e, quando valido, i formati E.164 normalizzati più metadati opzionali come tipo di linea, indicazioni di geocodifica e dati dell’operatore quando disponibili.
valid: true significa che il numero rispetta le regole di formato regionale (lunghezza, prefisso, sintassi). Non conferma che la linea sia attiva, assegnata a un abbonato o raggiungibile. Per lo stato della linea in tempo reale serve HLR/SMS lookup, che esula da questa API.

​
Per iniziare

​
REST

L’API di validazione dei numeri di telefono, come tutte le API Cleariflow, è organizzata attorno a REST. È progettata per usare URL prevedibili orientati alle risorse e codici di stato HTTP per indicare gli errori.

​
HTTPS

L’API di validazione dei numeri di telefono richiede che tutte le comunicazioni siano protette con TLS 1.2 o superiore.

​
Versioni API

Tutte le API Cleariflow sono versionate. L’API di validazione dei numeri di telefono è attualmente alla versione 1.

​
La vostra chiave API

La chiave API è la chiave di autenticazione univoca per l’API di validazione dei numeri di telefono Cleariflow. Ogni API Cleariflow ha una chiave API univoca, quindi serviranno chiavi diverse per accedere alla validazione telefonica e alla validazione e-mail, ad esempio. Per autenticare le richieste, aggiungete la chiave API all’URL di base.

​
URL di base

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

​
Cosa significa valid

validSignificato
trueIl numero è strutturalmente valido per la regione rilevata (libphonenumber IsValidNumber).
falseIl numero non è stato analizzabile o non rispetta le regole di formato regionale. format, country, location, type e carrier sono sempre vuoti; phone contiene solo le cifre del vostro input.
I numeri fittizi 555 statunitensi e altri intervalli strutturalmente validi ma non assegnati possono comunque restituire valid: true. carrier e location sono popolati principalmente dai metadati US/CA e spesso sono vuoti altrove.

​
Endpoint di validazione

L’API richiede la chiave API univoca e il numero di telefono da verificare: 
https://phonevalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& phone = 14155552671
& country = US
Risposta valida (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": ""
}
Risposta non valida (phone=123, country=US): 
{
  "phone": "123",
  "valid": false,
  "format": {
    "international": "",
    "local": ""
  },
  "country": {
    "code": "",
    "name": "",
    "prefix": ""
  },
  "location": "",
  "type": "Unknown",
  "carrier": ""
}

​
Parametri di richiesta

​
api_key
String
obbligatorio
La vostra chiave API univoca. Ogni utente ha chiavi API univoche per ciascuna delle API Cleariflow, quindi la chiave Phone Validation non funzionerà per l’API di geolocalizzazione IP, ad esempio.
​
phone
String
obbligatorio
Il numero di telefono da validare (controllo strutturale secondo libphonenumber).
​
country
String
Suggerimento opzionale ISO 3166-1 alpha-2 per numeri in formato nazionale senza + iniziale. Ad esempio, country=US aiuta ad analizzare 4155552671. I numeri con prefisso internazionale vengono analizzati dal codice paese; il country.code rilevato nella risposta può differire da questo suggerimento (es. GG per alcuni intervalli mobili +44).

​
Parametri di risposta

La risposta dell’API viene restituita in un formato JSON universale e leggero.
​
phone
String
Cifre E.164 normalizzate (senza +) quando valid è true. Quando valid è false, solo le cifre del vostro input.
​
valid
Boolean
true quando il numero è strutturalmente valido secondo libphonenumber. Questo non è verifica dello stato della linea o dell’abbonato.
​
format
Object
Formati international e local. Stringhe vuote quando valid è false.
​
format.international
String
Formato E.164 con + iniziale. Vuoto quando valid è false.
​
format.local
String
Formato nazionale per la regione rilevata. Vuoto quando valid è false.
​
country
Object
Paese/territorio rilevato. Campi vuoti quando valid è false.
​
country.code
String
Codice a due lettere ISO 3166-1 alpha-2 per la regione rilevata.
​
country.name
String
Nome visualizzato in inglese per country.code.
​
country.prefix
String
Prefisso telefonico internazionale (es. +1).
​
location
String
Indicazione di geocodifica dai metadati libphonenumber (regione, stato/provincia o città). Spesso vuota al di fuori di US/CA. Vuota quando valid è false.
​
type
String
Tipo di linea quando valid è true: Landline, Mobile, Landline_or_Mobile, Toll_Free, Premium, Paging, Special o Unknown. Sempre Unknown quando valid è false.
​
carrier
String
Nome dell’operatore dai metadati libphonenumber quando disponibile (più spesso US/CA). Stringa vuota altrimenti, incluso quando valid è false.

​
Caricamento massivo (CSV)

Buone pratiche per il caricamento massivo di un file CSV:
  • Assicuratevi che la prima colonna contenga i numeri di telefono da analizzare.
  • Rimuovete le righe vuote dal file.
  • Includete un solo numero di telefono per riga.
  • La dimensione massima consentita del file è di 50.000 righe.

​
Codici di risposta ed errore

Quando una richiesta fallisce per qualche motivo, viene restituito anche un errore in formato JSON. Gli errori includono un codice e una descrizione, dettagliati di seguito.
CodeTypeDetails
200OKTutto ha funzionato come previsto.
400Bad requestRichiesta non valida.
401UnauthorizedLa richiesta non era accettabile. Di solito per chiave API mancante o errata.
422Quota reachedLa richiesta è stata interrotta per crediti API insufficienti. (Piani gratuiti)
429Too many requestsLa richiesta è stata interrotta per aver raggiunto il limite di richieste al secondo. Nei piani gratuiti le richieste sono limitate a 1 al secondo.
500Internal server errorLa richiesta non è stata completata a causa di un errore lato server.
503Service unavailableIl server non era disponibile.

​
Altre note

Nota sulla fatturazione a consumo: ogni singolo numero di telefono inviato conta come un credito utilizzato. I crediti vengono conteggiati per richiesta, non per risposta riuscita. Quindi, se inviate una richiesta per il numero (non valido) «kasj8929hs», conta comunque come 1 credito.