FAQ Lookup API

Lookup risponde a domande su un destinatario prima che gli inviate un messaggio. Dategli un numero di telefono e vi dice cosa è quel numero: la rete che lo serve, il Paese, se ha cambiato rete e che tipo di linea è. Dategli un indirizzo email e vi dice se vale la pena inviargli un messaggio.

Due cose, un'operazione ciascuna. La verifica di un numero di telefono restituisce il Paese, la rete che serve il numero, la rete che lo ha emesso, se è passato dall'una all'altra e il tipo di linea, più qualsiasi proprietà richiesta. La verifica di un indirizzo email restituisce un verdetto, un punteggio di affidabilità e i flag che lo motivano.

Ogni verifica è una richiesta e una risposta. Non c'è nulla da creare, nulla da interrogare ciclicamente e nulla da ripulire dopo. Metodi tipizzati sono disponibili negli SDK Go, TypeScript, Python e PHP, e bird lookup phone-number e bird lookup email fanno lo stesso dalla CLI.

Sì. La pagina Lookup nella dashboard esegue le stesse due operazioni una alla volta, ed è il modo più rapido per vedere com'è una risposta prima di costruirci sopra.

Una chiave API con lo scope lookup e un wallet dell'organizzazione che possa coprire il costo. Il prezzo è per singola query senza costi per utente, quindi non c'è un piano da scegliere prima.

Usatelo quando volete decidere prima di agire: filtrare una registrazione, verificare un lead prima di lavorarci o instradare un messaggio diversamente in base al tipo di linea. Ottenete una risposta su cui agire senza dover prima inviare nulla.

Per query. Ogni ricerca viene addebitata sul wallet della vostra organizzazione. Una ricerca di numero di telefono viene fatturata una volta per la ricerca base, più un addebito per ogni proprietà che restituisce una risposta. Una ricerca di indirizzo email viene fatturata una volta per ogni indirizzo con risposta. Non ci sono costi per utenza.

La pagina dei prezzi di Lookup elenca la tariffa per la ricerca base, per ogni proprietà e per la ricerca di un indirizzo email. Le tariffe variano in base alla proprietà, perché ciascuna proviene da una fonte dati diversa.

No. Una proprietà viene addebitata solo quando viene consegnata. Una proprietà per cui non è stato possibile ottenere una risposta viene restituita con uno stato che lo indica e non costa nulla, e la ricerca base viene comunque servita insieme ad essa.

Non viene addebitato nulla. Un numero malformato, un indirizzo che rifiutiamo e una fonte dati non raggiungibile non hanno alcun costo.

Sì. Ogni indirizzo con risposta viene addebitato, inclusi quelli non recapitabili. Quella è la risposta che avete richiesto ed è quella che vi evita un bounce.

No, se inviate un Idempotency-Key. La ripetizione della stessa richiesta riproduce la risposta memorizzata anziché eseguire una nuova ricerca. I form GET, che inseriscono il numero o l'indirizzo nell'URL, non possono contenere una chiave di idempotenza, quindi usate POST per qualsiasi operazione automatizzata.

Il rate limit delle verifiche parte da 10 richieste al minuto, contate per credenziale attiva, così una chiave molto utilizzata non può bloccare le altre. Ogni verifica raggiunge una fonte dati esterna e addebita il wallet per la risposta, ecco perché parte dallo stesso livello dei limiti di invio.

Non al momento. Nessuna delle due operazioni ha una modalità batch, quindi controllare un'intera lista non è lo scenario per cui è dimensionato. Chiedeteci di alzare il limite se ne avete bisogno, anziché cercare soluzioni alternative.

Lo scope lookup a livello write. Non ha un livello read: ogni endpoint di verifica richiede write, incluso il recupero di un risultato già pagato. Owner e admin lo hanno di default, i member no.

Quattro rilevanti. E22000 quando il numero non è valido in formato internazionale, E22003 quando l'indirizzo non è un indirizzo email valido, E22001 quando il wallet dell'organizzazione non può coprire la verifica, e E22002 quando Lookup è temporaneamente non disponibile. Nessuno di questi viene addebitato.

No. Una proprietà che fallisce viene restituita come stato nel proprio blocco, con la verifica base servita accanto. Solo il fallimento della verifica base fa fallire la richiesta, e in quel caso fallisce del tutto anziché restituire una risposta semivuota che dovreste ispezionare per scoprire che era vuota.

La ricerca base restituisce il paese del numero, la rete che lo serve attualmente, la rete che ha assegnato il suo range, se è mai stato trasferito su un'altra rete e un tipo di linea generico. Viene sempre eseguita e, se non è possibile ottenere una risposta, l'intera richiesta fallisce anziché restituire una risposta incompleta.

Prima il prefisso internazionale, poi il numero nazionale. Il segno più iniziale è opzionale e 00 funziona al suo posto, quindi +31612345678, 31612345678 e 0031612345678 sono tutti lo stesso numero.

Un numero scritto per la composizione interna a un paese, senza prefisso internazionale, restituisce E22000 anziché essere interpretato a indovinare. Anteporre un prefisso internazionale a 0612345678 indicherebbe un numero reale altrove e vi addebiterebbe la ricerca di quel numero.

mobile, fixed_line, voip, toll_free, premium_rate, satellite, pager, payphone, m2m, service, other o unknown. unknown significa che la piattaforma dell'operatore non ha una classificazione per il range, e other significa che ne ha una senza equivalente qui. Richiedete la proprietà classification per il servizio assegnato con maggiore precisione.

network_info è la rete che serve il numero oggi e original_network_info è la rete che ha assegnato il suo range. Le due differiscono quando un numero è stato portato e, in tal caso, flags contiene ported. Richiedete la proprietà porting quando avete bisogno anche della data e del record completo.

Perché il numero non appartiene a un singolo paese, come nel caso di un range non geografico. I campi senza valore vengono omessi anziché restituiti come null, quindi ogni campo presente nella risposta è stato risolto.

No. Una ricerca non contatta mai il numero stesso. Legge i dati dell'operatore e di number intelligence, e le proprietà presence e roaming interrogano la rete su cui il numero è registrato, quindi nulla squilla e nulla arriva sul dispositivo.

Sei, indicate in type. classification per il servizio allocato preciso del range, porting per quando il numero è stato trasferito l'ultima volta e ogni spostamento registrato, presence per verificare se è attivo sulla rete in questo momento, roaming per sapere se è in roaming e su quale rete, sim_swap per quando la SIM è stata cambiata l'ultima volta e score per un punteggio di credibilità da 0 a 100.

Sì. classification, porting e score leggono dati memorizzati e rispondono rapidamente. presence, roaming e sim_swap interrogano la rete in tempo reale, quindi sono più lente e la loro copertura varia in base all'operatore. Per queste tre aspettatevi unavailable o inconclusive più spesso rispetto a quelle basate su dati memorizzati.

ok significa che la proprietà ha ricevuto una risposta, il suo valore è nella risposta ed è stata addebitata. unavailable significa che non è arrivata alcuna risposta e non è stata addebitata. inconclusive significa che è arrivata una risposta ma non risolve la proprietà, il che è un dato reale, e non è stata addebitata nemmeno in questo caso.

Sì, status è un vocabolario aperto. Gestite il caso ok e trattate tutto il resto come non risposto, così il vostro codice resta corretto indipendentemente dall'evoluzione del vocabolario.

porting fornisce la data e la cronologia completa, mentre il flag ported della ricerca base indica solo se è avvenuto uno spostamento. classification risolve line_type nel servizio allocato esatto, da una fonte diversa con un vocabolario più ampio, ed è riportata separatamente in modo che possiate sempre distinguere le due informazioni.

Perché la rete non ha rilasciato un valore esatto. sim_swap restituisce min_days e max_days anziché last_swapped_at quando è nota solo una fascia di recenza. porting fa qualcosa di simile: imposta last_ported_at_is_approximate quando un registro registra il periodo di uno spostamento ma non il giorno.

No. Significa che il registro è stato consultato e non contiene alcuno spostamento per questo numero, il che è un dato sul numero e non una lacuna nella risposta. È lo stato del blocco che indica se il controllo è stato eseguito o meno.

Come uno dei tanti segnali. Va da 0 per credibilità bassa a 100 per credibilità alta, è un valore composito e non è derivabile dalle altre proprietà. Valutalo insieme al resto della risposta anziché basare le decisioni solo su di esso.

Se l'indirizzo accetterà posta. Una singola chiamata restituisce un verdetto in result, un punteggio delivery_confidence, i flag che descrivono il tipo di indirizzo e una correzione quando l'indirizzo sembra contenere un errore di battitura.

valid significa che l'indirizzo esiste e accetta posta, quindi inviate. neutral significa che non è stato possibile confermare in nessun modo, di solito perché il dominio ricevente risponde allo stesso modo per ogni destinatario. risky significa che probabilmente accetta posta ma ha maggiori probabilità di generare un bounce o un reclamo. undeliverable significa che non accetta posta. typo significa che l'indirizzo sembra contenere un errore di battitura.

reason indica quale dei tre problemi è presente: invalid_syntax per un indirizzo malformato, invalid_domain quando il dominio non accetta posta, e invalid_recipient quando il dominio accetta posta ma questa casella non esiste.

Proponete did_you_mean a chi ha digitato l'indirizzo originale anziché inviare direttamente. La correzione è un'ipotesi, e l'indirizzo che intendevano potrebbe non essere nessuno dei due.

Va da 0, consegna certamente non riuscita, a 100, consegna certa. Lo stesso punteggio può trovarsi sotto verdetti diversi per ragioni diverse, quindi va letto insieme a result e non al suo posto. È il campo su cui basarsi quando si vuole un'unica soglia per tutti i verdetti, inclusi quelli aggiunti in futuro.

No, e la differenza è importante. Il campo valid è più restrittivo: indica se l'indirizzo è ben formato e se il suo dominio è configurato per ricevere posta. Non dice nulla sulla casella, quindi un indirizzo con un dominio funzionante ma senza tale casella risulta true lì e undeliverable in result.

role significa che l'indirizzo identifica una funzione anziché una persona, come support@ o info@, quindi risposte e consenso sono ambigui e i reclami più probabili. disposable indica un provider di indirizzi usa e getta, quindi l'indirizzo smetterà tipicamente di esistere. free_provider indica un provider di caselle consumer come Gmail o Outlook.com, un segnale rilevante solo quando ci si aspettava un indirizzo aziendale.

Inviate un indirizzo semplice, esattamente come lo avete. Un formato con display-name, con un nome davanti e l'indirizzo tra parentesi angolari, viene rifiutato anziché scomposto, perché scomporlo significherebbe verificare un indirizzo che non avete inviato. La parte prima della chiocciola viene passata così com'è, e cambiarne le maiuscole/minuscole può modificare il delivery_confidence ottenuto.

No. Le soppressioni lo fanno automaticamente e gratuitamente, per gli indirizzi che hanno già generato bounce o reclami. Usate Lookup per gli indirizzi a cui non avete ancora inviato, al momento della registrazione o prima di agire su un lead.