# 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**](https://bird.com/dashboard/w/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.

## What each lookup costs

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.

## The number lookup has two tiers

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.

## Only `ok` carries a value, and only `ok` is billed

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.

## Choosing between Lookup and validating on send

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](/docs/guides/email/suppressions) do that automatically and for free.

Neither operation has a batch form, and the `lookup` [rate limit](/docs/guides/rate-limits) 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.

## Next steps

- [Look up a phone number](/docs/guides/lookup/phone-numbers) covers the base lookup, every property, and what each one returns.
- [Look up an email address](/docs/guides/lookup/email-addresses) covers the verdicts and what to do with each.
- [Lookup API reference](/docs/api/reference/create-phone-number-lookup) documents every field.
- [Idempotency](/docs/guides/idempotency) explains how to retry a lookup without paying for it twice.