What formats can I send phone numbers in?

You can send numbers in international E.164 form (e.g. +14155552671), in which case the country is detected automatically, or in a local format (e.g. (415) 555-2671). For local formats, supply a country hint using the ISO 3166-1 alpha-2 code (US, GB, TR, etc.) so the parser knows which numbering plan to apply. Both GET requests with query parameters and POST requests with a JSON body are supported.

What does the API return for an invalid number?

Genuinely unparseable input returns a clean negative result with HTTP 200: { "input": "not-a-number", "valid": false, "possible": false }. The API does not throw errors for bad numbers, so you can branch on the valid and possible flags directly. A 400 status is reserved strictly for a missing number parameter or a malformed JSON body.

What is the difference between the valid and possible flags?

The possible flag checks only that the number has a plausible length and shape for its region, while the valid flag confirms the number fully conforms to that region's numbering plan. These independent flags let you choose your strictness: accept possible numbers during fast onboarding to reduce friction, then enforce full validity before billing or messaging customers.

Can the API tell if a number is mobile or fixed-line?

Yes. Every successful response includes a type field with the detected line type (such as MOBILE, FIXED_LINE, or FIXED_LINE_OR_MOBILE) plus convenience booleans is_mobile and is_fixed_line. This is ideal for deciding whether to send an SMS, place a voice call, or flag a suspicious signup. Note that for some numbering plans the type may be FIXED_LINE_OR_MOBILE when the plan does not distinguish between the two.

Which countries are supported?

The API is powered by Google's libphonenumber metadata, so it covers over 240 countries and territories — the same numbering-plan data used in production by Android and many major platforms. Coverage includes full validation, formatting, and line-type detection for each supported region's numbering plan.

How do I authenticate my requests?

Pass your API key as a query parameter, ?apikey=YOUR_KEY, or send it in an X-Api-Key header. All plans share the same full feature set and global edge latency.

The API is stateless and runs on a global edge network, delivering typical parse-and-format response times under 50ms. Because validation is performed locally against bundled libphonenumber metadata rather than calling out to external carriers, there is no network round-trip to a third party, keeping latency consistently low for production form validation and high-volume batch processing alike.

Validate, normalize, and format any phone number on Earth

Phone Number Validation & Formatting API

The Phone Number Validation & Formatting API turns messy, user-entered phone numbers into clean, trustworthy data. Send a raw string like (415) 555-2671 or +44 20 7183 8750 and receive a fully parsed result with validity flags, canonical E.164 form, national and international display formats, the RFC3966 tel: URI, detected country, and the line type.

Powered by Google's libphonenumber metadata, its numbering-plan coverage matches what major platforms use in production. Built for forms, signups, CRM hygiene, fraud screening, and SMS/voice routing, it runs stateless on a global edge network for low latency everywhere.

Get a free API key Read the docs

Free tier included, no credit card required. One key works across every API.

Free calls / month: 200
Countries: 240+
Parse Speed: <50ms
Uptime SLA: 99.9%

Get your free API key

200 free calls on the free plan

Key features

Validate and format any phone number worldwide
Canonical E.164, national, international, and RFC3966 formats
Line-type detection (mobile vs fixed-line)
Country and calling-code detection from ISO2 hints
Independent valid and possible flags for flexible strictness
Both GET (query params) and POST (JSON body) supported
Powered by Google libphonenumber metadata

Built for

Form and signup phone number validation
CRM data hygiene and normalization
Fraud screening and suspicious signup flagging
SMS vs voice routing decisions
Mobile vs fixed-line detection
Standardizing numbers to E.164 for storage
International contact data cleanup
Click-to-call link generation via tel: URIs

MCP · for your agent

Hand the Phone Number Validation API to your agent

Connect Claude, Cursor or any MCP client once, then ask in plain words. Your agent finds this API, reads its docs and makes the call: 5 credits per call, the same as REST, from your team's balance.

Connect your agent

Clean up CRM phone numbers

“Clean the phone column in our CRM export: put every US number in +1 international format and flag the invalid ones.”

list_apis · get_api_docsfree

api_request GET /phone/v1/validate?number=(415)+555-0132&country=US 5 cr

E.164, national and international formats per number, with invalid ones flagged.

Choose SMS or a voice call

“Before we send appointment reminders, which of these UK numbers are mobiles that can get texts?”

list_apis · get_api_docsfree

api_request POST /phone/v1/validate 5 cr

Line type per number: mobiles marked for SMS, landlines queued for a voice reminder.

Screen a suspicious signup

“A signup gave +44 7700 900123 but came from a German IP. Is the number valid, and which country and line type is it?”

list_apis · get_api_docsfree

api_request GET /phone/v1/validate?number=%2B447700900123 5 cr

+ IP Intelligence API5 cr

Validity, country and line type for the number, compared with the signup IP's network.

$ claude mcp add --transport http apicodex https://mcp.apicodex.io

Illustrative asks; the calls and prices are real. Claude, Cursor, VS Code and Windsurf setup: mcp.apicodex.io

Try it

Build the request for your data

Edit the parameters below and see the exact request and curl command you'd send. No key required to preview.

GET /phone/v1/validate

Open in Playground

Parameters

number

country

apikey

Request · HTTP

GET /phone/v1/validate?number=(415)%20555-2671&country=US&apikey=YOUR_KEY HTTP/1.1
Host: api.apicodex.io

Response · JSON 200 OK

{
"input": "(415) 555-2671",
"valid": true,
"possible": true,
"e164": "+14155552671",
"national": "(415) 555-2671",
"international": "+1 415 555 2671",
"rfc3966": "tel:+14155552671",
"uri": "tel:+14155552671",
"country": "US",
"country_calling_code": "1",
"type": "FIXED_LINE_OR_MOBILE",
"is_mobile": false,
"is_fixed_line": false
}

Run it with your key

Documentation

Phone Number Validation API Documentation

The Phone Number Validation & Formatting API parses, validates, and formats phone numbers worldwide using Google's libphonenumber metadata with line-type detection. Pass a number alone if it is already in international +E.164 form, or add a country hint (e.g. US, GB, TR) to parse local-format numbers. Both GET (query params) and POST (JSON body) requests are supported.

Base URL

url

https://api.apicodex.io/phone

Authentication

Authenticate every request with your API key: pass it as a query parameter, or send it in an X-Api-Key header.

headers

?apikey=YOUR_KEY

# Or send it as a header:
{
"X-Api-Key": "YOUR_API_KEY"
}

Request and response

Illustrative values. Confirm current endpoint behavior, quotas, and data freshness in the API documentation before production use.

request · http

GET /phone/v1/validate?number=(415)%20555-2671&country=US&apikey=YOUR_KEY HTTP/1.1
Host: api.apicodex.io

response · json

{
"input": "(415) 555-2671",
"valid": true,
"possible": true,
"e164": "+14155552671",
"national": "(415) 555-2671",
"international": "+1 415 555 2671",
"rfc3966": "tel:+14155552671",
"uri": "tel:+14155552671",
"country": "US",
"country_calling_code": "1",
"type": "FIXED_LINE_OR_MOBILE",
"is_mobile": false,
"is_fixed_line": false
}

Code examples

cURL

curl --request GET \
  --url 'https://api.apicodex.io/phone/v1/validate?number=(415)%20555-2671&country=US&apikey=YOUR_KEY'

JavaScript/Node.js

const params = new URLSearchParams({
  number: '(415) 555-2671',
  country: 'US',
  apikey: 'YOUR_KEY'
});

const url = 'https://api.apicodex.io/phone/v1/validate?' + params;

try {
  const response = await fetch(url);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Python

import requests

url = "https://api.apicodex.io/phone/v1/validate"

querystring = {
    "number": "(415) 555-2671",
    "country": "US",
    "apikey": "YOUR_KEY"
}

response = requests.get(url, params=querystring)

print(response.json())

Endpoints

GET /v1/validate

Validate and format a phone number using query parameters.

/v1/validate?number=(415)%20555-2671&country=US&apikey=YOUR_KEY

POST /v1/validate

Validate and format a phone number using a JSON request body.

{ "number": "+442071838750", "country": "GB" }

Parameters

Required parameters

number The phone number to validate. May be E.164 (e.g. +14155552671) or a local format (e.g. (415) 555-2671) when a country is supplied.

Optional parameters

country Optional ISO 3166-1 alpha-2 region used as the default country when the number is not in +E.164 form (e.g. US, GB, TR).
apikey Your API key, passed as a query parameter for authentication when calling the Worker directly.

Pricing

Phone Number Validation API Pricing

This API costs 5 credits per request. Credits are shared across every API on your plan.

Estimate your monthly cost

Drag the slider to match your expected request volume. We'll recommend the cheapest plan that covers it.

Requests per month 10,000

Recommended plan

Starter

$29.99 /month

Credits used

Credits included

Cost per 1K requests

Choose Starter

Free

1,000 credits · ~200 requests/mo · 2 rps

All APIs included
No credit card required
Full documentation and examples
MCP server for your AI agents
Up to 5 active API keys

Start for free

Starter

Popular

$29.99 /month

50,000 credits · ~10,000 requests/mo · 10 rps

All APIs included
Email support
Usage dashboard and analytics
MCP server for your AI agents
Up to 5 active API keys

Start with Starter

Pro

$99.99 /month

250,000 credits · ~50,000 requests/mo · 25 rps

All APIs included
Priority support
MCP server for your AI agents
Up to 5 active API keys

Start with Pro

FAQ

Phone Number Validation & Formatting API

Key features

Built for

Hand the Phone Number Validation API to your agent

Clean up CRM phone numbers

Choose SMS or a voice call

Screen a suspicious signup

Build the request for your data

Phone Number Validation API Documentation

Base URL

Authentication

Request and response

Code examples

Endpoints

GET /v1/validate

POST /v1/validate

Parameters

Required parameters

Optional parameters

Phone Number Validation API Pricing

Free

Starter

Pro

Need a different plan?

Frequently asked questions

Related APIs