Lookup overview

Lookup answers questions about a recipient before you send to them. Give it a phone number and it tells you what the number is: the network serving it, the country, whether it has moved network, and what kind of line it is. Give it an email address and it tells you whether the address is worth sending to.

Both are one request and one answer. There is nothing to create, nothing to poll, and nothing to clean up afterwards. The Lookup page in the dashboard runs the same two operations one at a time, which is the fastest way to see what an answer looks like before you write any code.

Every lookup is charged to your organization's wallet, and this is the part worth understanding before you build on it.

A phone number lookup always bills once for the base lookup. On top of that you can request properties, extra facts that come from a paid data source. Each property you request is billed separately, but only when it is delivered. A property that could not be answered comes back with a status saying so and costs you nothing.

An email address lookup bills once per answered address. Every verdict is billed, undeliverable included: that is the answer you asked for, and it is the one that saves you a bounce.

Nothing is billed when a lookup fails. A malformed number, an address we refuse, or a data source that cannot be reached all cost nothing.

This split is the whole design of the phone number lookup, so it is worth being explicit about.

The base lookup always runs. It answers the serving network, the network that issued the number, the country, whether the number has ever moved network, and a coarse line_type (mobile, fixed line, VoIP, toll-free, and so on). If the base lookup cannot be answered, the whole request fails rather than returning a half-empty answer you would have to inspect to discover was empty.

Properties are what you add on top, by naming them in type. They answer finer questions: the precise allocated service of the range, the full porting record, whether the number is live on the network right now, whether it is roaming, when its SIM last changed, and a credibility score. A property that cannot be answered never fails the request. It degrades to a status, and the base lookup is still served.

Every property block has a status, and reading it is not optional.

ok means the property was answered, its value is in the response, and it was billed.

unavailable means no answer arrived, so the property adds nothing. It was not billed.

inconclusive means an answer arrived but does not resolve the property: the number sits outside the coverage of the data behind it, or the source returned a value this property does not report. It is a real finding rather than a missing one, and it was not billed either.

status is an open vocabulary, so more values may be added. Branch on ok and treat everything else as "not answered" and your code stays correct however it grows.

Lookup is for deciding before you commit, one recipient at a time: checking a number or address at signup, screening a lead before you act on it, or routing a message differently depending on what the line turns out to be. It costs money per check and gives you an answer you can act on.

If you only want to stop sending to addresses that have already bounced or complained, you do not need Lookup. Suppressions do that automatically and for free.

Neither operation has a batch form, and the lookup rate limit starts at 10 requests a minute per credential, so checking a whole list is not what this is sized for today. Talk to us about raising the limit if that is what you need.