Domande e risposte
Domande su Lookup, con risposta.
Scopri quali controlli si adattano ai contatti che devi verificare.
Realizzato con BirdStorie dei clienti
Storie dei clientiRealizzato con Bird
Scelto dai team di ingegneria e di prodotto che rilasciano su scala globale.
Domande frequentiSpiegazioni
SpiegazioniDomande frequenti
FAQ Lookup API
Cos'è Bird Lookup?
Bird Lookup verifies phone numbers and email addresses before you send a message or accept a signup. For a phone number, it returns the country, serving and issuing carriers, porting status, line type, and optional network checks. For an email address, it returns a deliverability verdict, confidence score, inbox type flags, and suggested typo corrections.
Cosa posso verificare?
You can check phone numbers and email addresses through dedicated endpoints. A phone number lookup returns the country, serving carrier, original issuing carrier, porting status, and line type, along with any optional enrichment properties you request. An email address lookup validates a single address or a synchronous batch and returns a deliverability verdict, confidence score, and address classification flags.
Quanto impegno richiede l'integrazione?
A lookup completes in a single synchronous request and response without webhook setup or polling. You can call the REST endpoints directly, use typed methods in the Go, TypeScript, Python, and PHP SDKs, or run phone number and email lookups from the terminal with the Bird CLI.
Posso eseguire una verifica senza scrivere codice?
Yes. You can check individual phone numbers and email addresses directly from the Lookup page in the Bird dashboard to inspect carrier details, enrichment properties, and deliverability verdicts before integrating the API.
Di cosa ho bisogno prima della prima verifica?
You need an API key with lookup write permission and a funded organization wallet. Lookups are billed per query without monthly seat fees or upfront plan commitments.
Quando dovrei usare Lookup invece di inviare direttamente?
Use Lookup when you want to verify contact details before spending on delivery or admitting an account. Common workflows include blocking disposable emails and virtual numbers at signup, screening lead lists before outreach, and routing OTPs to voice instead of SMS when a number is a landline.
Come viene tariffato Lookup?
Lookups are billed per query from your organization's wallet with no seat fees. A phone number lookup charges a base rate plus an individual fee for each requested enrichment property that returns an answer. An email address lookup charges per validated address.
Dove trovo le tariffe?
The Lookup pricing page lists the per-query rate for a base phone number lookup, each optional enrichment property, and an email address lookup. Property rates vary because each check queries a distinct carrier or intelligence data source.
Pago per una proprietà che viene restituita vuota?
No. You are charged for an enrichment property when it returns a resolved answer. If a property is unavailable or inconclusive, its status explains why at no charge for that property, and you still receive the base phone number lookup.
Cosa succede alla mia fatturazione quando una ricerca fallisce?
Le richieste non riuscite non vengono addebitate. Se un numero di telefono o un singolo indirizzo email ha un formato non valido, o se una fonte di dati a monte non è raggiungibile, il tuo wallet non viene addebitato. Un batch di email restituisce una valutazione per ogni indirizzo e addebita ciascuno, inclusi gli indirizzi con formato non valido.
Mi viene addebitato un indirizzo che risulta non recapitabile?
Yes. Validated email addresses are billed regardless of the deliverability verdict, including undeliverable addresses. Identifying an invalid mailbox upfront prevents a hard bounce and protects your sender reputation.
Un nuovo tentativo può addebitarmi due volte?
Invia un Idempotency-Key con una richiesta di lookup POST. Se riprovi con la stessa chiave e la stessa identica richiesta nello stesso spazio di lavoro entro tre ore, ricevi la risposta memorizzata senza che venga eseguito né addebitato un altro lookup. Dopo tre ore, o quando nessuna risposta è stata conservata, ad esempio per una risposta di un batch email superiore a 256 KiB, un nuovo tentativo può eseguire e addebitare di nuovo il lookup o il batch. Le forme GET, che inseriscono il numero o l’indirizzo nell’URL, non accettano chiavi di idempotenza, quindi usa gli endpoint POST per i flussi di lavoro automatizzati.
Quante verifiche posso eseguire al minuto?
Dipende dal limite di richieste Lookup della tua organizzazione. La tua organizzazione condivide il limite tra tutte le sue chiavi API e i suoi spazi di lavoro, quindi creare un’altra chiave non aumenta la capacità, e un batch email fino a 1.000 indirizzi conta come una sola richiesta. Gli header di limitazione delle richieste nelle risposte Lookup mostrano il limite che si applica alla tua richiesta. Poiché ogni lookup interroga fonti di dati esterne di operatori o domini e viene addebitato sul tuo wallet, le nuove organizzazioni partono con un limite prudente. Contattaci per aumentarlo man mano che il tuo volume cresce e consulta la guida Rate limits nella documentazione per capire come leggere gli header.
Esiste una verifica batch o in blocco?
Email address lookup supports synchronous batches of up to 1,000 addresses in a single request, with a maximum request body of 128 KiB. Phone number lookup checks one number per request, and you can contact us to raise your rate limit for higher-throughput phone verification.
Quale scope serve per una verifica?
Lookup endpoints require the lookup permission scope with write access. Because lookups trigger billable external queries and do not expose separate read-only endpoints, write permission is required across the API. Workspace owners and admins have this access by default.
Quali errori può restituire una verifica?
Lookups return specific error responses when a phone number is missing a valid international country code, when an email address is malformed, when your organization's wallet has insufficient balance to cover the query, or when an upstream lookup service is temporarily unavailable. Failed requests do not charge your wallet.
Una proprietà che non può ricevere risposta fa fallire la mia richiesta?
No. When an optional enrichment property cannot be resolved, it returns an unavailable or inconclusive status on its own section of the response while the base phone number lookup still succeeds. A request fails outright when the base lookup itself cannot be completed.
A cosa risponde una ricerca di numero di telefono?
A base phone number lookup returns the number's country, its current serving carrier, the carrier that originally issued the number range, whether the number has been ported between carriers, and its general line type. If the base lookup cannot be resolved, the request returns an error rather than an incomplete response.
Come devo scrivere il numero?
Format the number in international E.164 order with the country calling code followed by the national number. You can include a leading plus sign, omit it, or use a 00 international prefix, so +31612345678, 31612345678, and 0031612345678 resolve to the same Dutch mobile number.
Perché il mio numero è stato rifiutato?
Numbers written in local national format without a country calling code are rejected instead of guessed. Automatically prepending a country code to a local string like 0612345678 could match an unrelated international number and bill your wallet for the wrong lookup.
Quali tipi di linea può restituire?
The base lookup classifies numbers into mobile, landline, VoIP, toll-free, premium-rate, satellite, pager, payphone, machine-to-machine, service, other, or unknown line types. An unknown result means the carrier registry has no classification for that number range, while other indicates a specialized category outside the standard list. You can request the line classification property when you need finer detail on the allocated service.
Come faccio a sapere se un numero è stato portato?
The base response includes both the serving carrier that routes the number today and the original carrier that was allocated the number block. When a subscriber moves their number to a new operator, those two carrier blocks differ and the response includes a ported indicator. Add the porting history property when you need the date of the most recent move and the full record of carrier transfers.
Why is the country code missing from my answer?
Some international numbering ranges, such as global satellite or non-geographic services, are not assigned to a single country. When a field has no applicable value, the response omits it rather than returning an empty placeholder, so each field present in the payload reflects a resolved value.
Una ricerca chiama o invia messaggi al numero?
No. A lookup does not place a call or send a message to the recipient's device. Base lookups read carrier and numbering registries, and live checks such as network presence and roaming status query operator signaling networks silently without alerting the handset.
Quali proprietà posso aggiungere a una ricerca di numero di telefono?
You can request up to six optional enrichment properties on a phone number lookup: line classification for the precise service allocated to the number range, number porting history for the dates and carrier records of past network moves, live network presence to check whether the handset is currently reachable, active roaming status and the visited network, SIM swap recency to detect recent SIM card changes, and a credibility score from 0 to 100.
Alcune proprietà sono più lente di altre?
Yes. Line classification, number porting history, and the credibility score read indexed registry data and return with minimal latency. Live network presence, active roaming status, and SIM swap recency query the subscriber's mobile operator in real time, so they take longer to resolve and return unavailable or inconclusive statuses more frequently depending on carrier coverage.
Cosa significano gli stati delle proprietà?
Each requested property returns its own status. An answered status means the check succeeded, the property data is included in the response, and the property was billed. An unavailable status means the carrier or registry did not return data, at no charge. An inconclusive status means the upstream source responded without enough information to resolve the check definitively, which is also unbilled.
Possono comparire nuovi stati in futuro?
Yes. The status field uses an extensible set of values so new diagnostic states can be introduced without breaking existing integrations. Check for an answered status before reading the property data, and treat any other status as an unresolved check.
What do porting history and line classification add over the base answer?
While the base lookup indicates whether a number currently sits on a different carrier than the one that issued its range, the porting history property provides the timestamp of the latest transfer and the historical log of carrier moves. Line classification consults a more granular numbering registry to report the specific service allocated to the range alongside the base line type.
Why did the SIM swap check return a day range instead of an exact date?
Some mobile operators disclose SIM swap recency as a time window rather than an exact timestamp to meet regional privacy rules. When an operator reports a recency band, the response provides the minimum and maximum days since the last SIM change instead of a specific timestamp. Similarly, the porting history property flags when a national registry records the month or period of a carrier transfer rather than the exact calendar day.
Does an unported result mean the porting check failed?
No. When the porting history property reports that a number has not been ported, the national registry confirmed that the number still resides with its original issuing carrier. Check the property status field to see whether the registry query itself succeeded or was unavailable.
Come si legge il punteggio?
Treat the credibility score as one risk signal alongside line type, porting history, and SIM swap recency. The score ranges from 0 for low credibility to 100 for high credibility based on composite numbering intelligence that goes beyond the other individual properties, so it works best when combined with your own application rules.
A cosa risponde una verifica di indirizzo email?
An email address lookup tells you whether a mailbox is ready to receive mail before you send to it. One request returns a deliverability verdict, a delivery confidence score from 0 to 100, classification flags for role, disposable, and free consumer inboxes, and a suggested typo correction when the domain looks misspelled.
Quali sono i cinque verdetti?
A valid verdict means the mailbox exists and accepts mail. A neutral verdict means the receiving server accepts mail for the domain without confirming individual mailboxes, as catch-all domains do. A risky verdict means the address can receive mail but carries higher bounce or complaint risk, such as a disposable or role-based inbox. An undeliverable verdict means the address cannot receive mail, and a typo verdict flags a likely domain misspelling.
Perché un indirizzo risulta undeliverable?
When an address is marked undeliverable, the response specifies whether the failure comes from a syntax error in the address format, a non-existent or unconfigured mail domain, or an invalid mailbox that the receiving domain rejected.
Cosa devo fare con un verdetto typo?
Present the suggested typo correction in your signup or checkout form so the user can confirm it before you send mail. Automatically rewriting an email address without confirmation risks sending sensitive account messages to the wrong person if the original address was intentional.
How does the delivery confidence score differ from the verdict?
The delivery confidence score scales from 0 for an address that will bounce to 100 for a verified, deliverable mailbox. Because different risk factors can produce similar numeric scores under different verdicts, use the verdict to choose the workflow action, such as prompting for a typo fix, and use the confidence score when you want a numeric threshold for list filtering.
How does basic format and domain validity differ from a valid verdict?
The boolean validity indicator checks whether the email address is syntactically well-formed and belongs to a domain configured to accept mail. It does not verify the individual mailbox, so an address at a working domain with a non-existent username passes basic domain validity while still receiving an undeliverable verdict.
Cosa significano i flag?
Role addresses identify shared team inboxes such as support@ or info@, where individual consent is harder to track and complaint rates are higher. Disposable inbox providers issue short-lived throwaway addresses often used to bypass signup gates. Free consumer mail providers such as Gmail or Outlook.com help B2B forms distinguish personal addresses from company domains.
Come devo scrivere l'indirizzo?
Pass the bare email address without a display name or angle brackets. Addresses wrapped in display-name headers are rejected so the API validates the exact string you store. Preserve the original casing of the local part before the @ symbol, since some mail servers treat local-part casing as significant when scoring deliverability.
Ho bisogno di Lookup per smettere di inviare a indirizzi che hanno già generato un bounce?
No. Bird's suppression list automatically blocks repeat sends to addresses that have already bounced or reported spam at no extra charge. Use Lookup to screen new email addresses before your first send, such as during account registration, checkout, or lead import.
Explore the Lookup API
See how phone number verification, email validation, and per-query pricing work across your signup and messaging flows.
- Ricerca numero di telefonoIdentify the country, serving and issuing carriers, porting state, line type, and six optional network properties before you send an SMS or place a call.
- Ricerca indirizzo emailCheck deliverability verdicts, confidence scores, role and disposable inbox flags, and suggested typo corrections before sending email.
- PrezziReview per-query rates for base phone number lookups, email validations, and optional enrichment properties that return an answer.
- La API LookupValidate phone numbers and email addresses from one API to block fake signups, prevent bounces, and route messages by line type.
Verify recipients before you send a message.
Talk with our team about screening signups, choosing carrier and network checks for your risk model, or sizing throughput for high-volume verification.
La tua prossima ideaInizia a sviluppare
Inizia a sviluppareLa tua prossima idea