Phone Numbering-Plan Validation

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.

POST https://YOUR_API_HOST/v1/phone

Credits and caching

• Success billing. 1 credit per valid number. You are charged only when the lookup finds something; a not-found result is free.
• Results are cached per account for 7 days. Repeating the same lookup in that window is free and returns cache_hit: true.
• Invalid input, rate limits and errors are never charged.
• Read the billing rules for the full picture.

Request

Send a JSON body with Authorization: Bearer <key>. The body can be up to 64 KB.

Example request

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

1const response = await fetch("https://YOUR_API_HOST/v1/phone", {
2  method: "POST",
3  headers: {
4    Authorization: `Bearer ${process.env.LOOKVALID_API_KEY}`,
5    "Content-Type": "application/json",
6  },
7  body: JSON.stringify({
8    "phone": "+12025550143"
9  }),
10});
11​
12const result = await response.json();
13if (!response.ok) throw new Error(`${result.error.code}: ${result.error.fix}`);
14console.log(result.found, result.data, result.credits_charged);

1import os
2import requests
3​
4response = requests.post(
5    "https://YOUR_API_HOST/v1/phone",
6    headers={"Authorization": f"Bearer {os.environ['LOOKVALID_API_KEY']}"},
7    json={
8        "phone": "+12025550143",
9    },
10    timeout=30,
11)
12result = response.json()
13if not response.ok:
14    raise RuntimeError(f"{result['error']['code']}: {result['error']['fix']}")
15print(result["found"], result["data"], result["credits_charged"])

Response

The status is 200 whether or not anything was found. Check found. Every response also carries the X-Request-Id, X-Credits-Charged, X-Credits-Remaining and X-RateLimit-* headers.

Envelope

The data object

Present when found is true, otherwise null.

Captured example (2026-10-18)

A real run of this lookup on 2026-10-18, using the request above, which is a public input. The envelope fields are left out.

1{
2  "product": "phone",
3  "found": true,
4  "data": {
5    "valid": true,
6    "possible": true,
7    "e164": "+12025550143",
8    "national_format": "(202) 555-0143",
9    "international_format": "+1 202 555 0143",
10    "country_calling_code": "1",
11    "country": "US",
12    "number_type": "fixed_line_or_mobile",
13    "line_type_source": "numbering-plan",
14    "carrier": null,
15    "area_code": "202",
16    "area_code_region": {
17      "code": "DC",
18      "name": "District of Columbia"
19    },
20    "extension": null,
21    "notes": "Line type comes from the numbering plan, not from a carrier. Carrier, porting, line status and reachability are not included; this check cannot say whether the number is active or has been moved to another carrier."
22  },
23  "sources": [
24    "Google libphonenumber metadata (Apache-2.0)",
25    "NANPA area code report (nanpa.com)"
26  ]
27}

Errors

• 400 invalid_input: The request input is invalid.
• 401 unauthorized: The API key is missing, malformed, revoked or unknown.
• 402 insufficient_credits: The account does not have enough credits for this lookup. Error code: insufficient_credits. During a trial whose allowance is used up the code is trial_allowance_exhausted: nothing is charged and the customer starts the plan from the billing page.
• 405 method_not_allowed: This endpoint does not accept that HTTP method.
• 413 payload_too_large: The request body is too large.
• 429 rate_limited: Too many requests for this API key.
• 500 internal_error: An unexpected error occurred.
• 503 provider_unavailable: The data source for this product is unavailable right now.