Vai al contenuto principale
GET
API di validazione numeri di telefono
L’uso è molto semplice: inviate la chiave API e un numero di telefono. L’API restituisce se il numero è strutturalmente valido e, se valido, formati E.164 normalizzati e metadati opzionali come tipo di linea, geocodifica, operatore, fusi orari e indicazioni di composizione 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 carrier 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

Cosa significa valid

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:
Risposta valida (phone=14155552671, country=US):
Risposta non valida (phone=123, country=US):

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.
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. Questo non è verifica dello stato della linea o dell’abbonato.
possible
Boolean
Controllo di lunghezza permissivo (). true quando cifre e lunghezza potrebbero appartenere a un numero reale, anche se valid è false.
invalid_reason
String
Presente quando valid è false. Uno tra: not_a_number, possible, possible_local_only, invalid_country_code, too_short, invalid_length, too_long, unknown. Omesso quando valid è true.
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
location
String
Indicazione di geocodifica (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 quando disponibile (più spesso US/CA). Stringa vuota altrimenti, incluso quando valid è false.
carrier_display
String
Nome operatore sicuro per la visualizzazione utente (numero valido e regione senza portabilità mobile). Vuoto se valid è false o l’operatore non può essere mostrato in modo sicuro.
timezones
Array
Identificatori di fuso orario IANA (es. America/New_York). Array vuoto se valid è true senza mapping; null se valid è false.
geographical
Boolean
Indica se il numero è associato a una regione geografica. Sempre false quando valid è false.
internationally_dialable
Boolean
Indica se il numero può essere chiamato dall’esterno della regione di origine. Sempre false 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.

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.