Phone validation API
A phone validation API that returns a verdict
Send a number as JSON with your API key and read back the line type, the carrier and a verdict: textable, callable, invalid or unknown.
curl -X POST https://numberlookup.io/v1/phone \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"number": "+14155550132"}'What you get
What you get back
Every field below is in the API response, with the type to expect.
| Field | Type | What it means |
|---|---|---|
number_e164 | string | null | The number in international format, such as +14155550132. null when it could not be read. |
valid | boolean | Whether the number can be a real one. This is a format and numbering check, not proof that anyone answers. |
country | string | null | The two-letter country code, such as US or CA. |
region | string | null | The two-letter state or province code, such as CA or ON. null when we have none. |
line_type | string | null | The kind of line: mobile, fixed_line, voip, toll_free and the other types a carrier reports. null when unknown. |
carrier | string | null | The carrier that holds the number, as our data source names it. |
ported | boolean | null | Whether the number was moved between carriers. null when the data source does not say. |
voip | boolean | true for an internet (VoIP) number. Texting one is unreliable. |
verdict | string | The short answer for the row: textable, callable, invalid or unknown. |
reason | string | Why the verdict is what it is, such as mobile, bad_format or outside_coverage. |
partial | boolean | true when our data source did not answer, so only the format and exchange checks ran. The verdict is then unknown and nothing is charged. |
credits_used | number | The credits this call took: 0 or 1. |
credits_remaining | number | Your balance after this call. |
Verdicts
A verdict for every row
Read the verdict first. The reason field says how we got there.
| Verdict | What it means | What to do with the row |
|---|---|---|
| Valid · Mobile | A mobile number. It can be called and texted. | Keep it. Whether you may text it depends on consent, and this check does not look at consent. |
| Valid · Landline | A line that can be called: a landline, a toll-free number, VoIP or another type. A VoIP number is flagged because texting it is unreliable. | Call it. Do not count on texts, and send VoIP rows to your call list. |
| Invalid | Not a working number. It is not a real phone number, or no carrier holds its exchange. | Drop the row. If the number looks like a typo, fix it and check it again. |
| Unknown | We could not tell what the number is. You are not charged. | Set the row aside and check it again later if it matters. |
Verdicts describe reachability. They are not compliance checks.
How it works
How it works
Four steps, and none of them needs a call with us.
- Step 1
Create an API key
Make a key on the API keys page of your dashboard. It is shown once, so copy it then.
- Step 2
Send a number
POST the number as JSON to /v1/phone, with your key as a bearer token.
- Step 3
Read the verdict
The reply holds the verdict, the reason, the line type, the carrier and your remaining credits.
- Step 4
Pay only for answers
Unknown results and errors cost 0 credits. Every reply says what the call cost.
Limits
What this check cannot tell you
Knowing where a check stops is what lets you trust the part that works.
- Live data covers numbers in the United States and Canada. A valid number anywhere else gets a format check, the verdict unknown and no charge.
- Carrier answers are cached, so a number that changed carrier very recently may still show the old one.
- We do not say who owns a number. A carrier is a company, not a person, and we do not look people up.
- A number that was real once and is now out of service can still come back callable. A carrier lookup shows what kind of line a number is, not whether anyone picks up.
FAQ
Questions about this check
Short answers. If yours is not here, write to support@numberlookup.io.
How do I get an API key, and what does a call cost?
Create an account, open API keys in your dashboard and make a key. It is shown once, so copy it then. A call to the phone or IP endpoint costs 1 credit, or nothing when the result is unknown or the call fails. New accounts start with free credits and need no card.
What am I charged when a result is unknown?
Nothing. A result of unknown costs 0 credits. So does input that is not a phone number at all, an empty row and any error. In a bulk list, duplicate rows are free, and rows that come back unknown are returned to your balance when the list finishes.
What does each verdict mean?
Textable is a mobile number, which can be called and texted. Callable is a line that can take calls, such as a landline, a toll-free number or a VoIP number. Invalid is not a working number. Unknown means we could not tell, and you are not charged. A verdict says whether a number can be reached. It says nothing about whether you may contact it.
Do credits expire?
No. Credits from a pack never expire, credits from a plan never expire, and neither do the free credits you get at sign-up. If you cancel a plan, the credits already on your account stay there.