How each product works

How to use Phone Numbering-Plan Validation

What Phone Numbering-Plan Validation takes in, which fields it returns and how credits are charged for each lookup.

Last updated 2026-10-22

What it does

Checks a phone number against its country's numbering plan and returns E.164, national and international formats, the country and the number type the plan assigns (mobile, fixed line, toll free, VoIP and others). Uses open libphonenumber metadata only: it does not query carriers, so it cannot tell whether a number is active, ported or reachable.

What you send

Send these fields in the JSON body of the request.

Request fields for Phone Numbering-Plan Validation
Field	Type	Required	Limits
phone	string	Required	up to 64 characters
country	string	Optional	up to 8 characters

Request fields for Phone Numbering-Plan Validation

What you get back

The data object of a successful response carries these fields. Every response also lists its sources, the credits_charged and whether it was a cache_hit.

Each field is described in the API reference.

Response fields for Phone Numbering-Plan Validation
Field	Type
valid	boolean
possible	boolean
e164	string
national_format	string
international_format	string
country_calling_code	string
country	string
number_type	"mobile" or "fixed_line" or "fixed_line_or_mobile" or "voip" or "toll_free" or "premium_rate" or "shared_cost" or "personal_number" or "pager" or "uan" or "unknown"
line_type_source	string
carrier	null
area_code	string
area_code_region	object or null
extension	string
notes	string

Response fields for Phone Numbering-Plan Validation

What it costs

1 credit per valid number.

What each outcome costs
Case	Charge
Found	1 credit
Nothing found	0 credits
Repeat inside 7 days	0 credits
Errors and invalid requests	0 credits

What each outcome costs

Run it

You can try it without an account in the free tool. The free tools share a limit per visitor.

From code, send a POST request to https://YOUR_API_HOST/v1/phone with your API key.

1curl -X POST https://YOUR_API_HOST/v1/phone \
2  -H "Authorization: Bearer $LOOKVALID_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"phone":"+12025550143"}'

A request to Phone Numbering-Plan Validation

Full parameters and response fields are in the API reference. To run a list of values, use a bulk CSV job.

Good to know

A repeat of the same lookup within 7 days is served from your cache and costs 0 credits.
When the lookup finds nothing it returns found: false and costs 0 credits.
Invalid input and errors are never charged.
The API allows 200 requests per 10 seconds per key.

Still stuck? Write to hello@lookvalid.com.