How to validate and format a phone number with an API
POST a phone number to /v1/phone. It returns whether the number fits its country's numbering plan, its E.164, international, national and RFC 3966 forms, the region, number type, location and time zones.
Request
number is in international form (+CC ...) or in national form together with region, an ISO 3166-1 alpha-2 code such as US.
curl -s -X POST https://tanod.dev/v1/phone \
-H 'X-Tanod-Free: 1' -H 'content-type: application/json' \
-d '{"number": "+1 202 555 0100"}'Response
{
"valid": true,
"possible": true,
"e164": "+12025550100",
"international": "+1 202-555-0100",
"national": "(202) 555-0100",
"rfc3966": "tel:+1-202-555-0100",
"country_calling_code": 1,
"region": "US",
"type": "fixed_line_or_mobile",
"location": "Washington D.C.",
"timezones": ["America/New_York"],
"source": {
"library": "phonenumbers 9.0.40",
"license": "Apache-2.0",
"url": "https://github.com/daviddrysdale/python-phonenumbers"
},
"note": "Offline numbering-plan check: 'valid' means the number fits its …"
}Limits and caveats
Format, not reachability. valid means the number fits the numbering plan. It does not mean the number is assigned, in service or reachable, and no call or SMS is sent. To confirm ownership, send a verification code.
Carrier is the original range holder. Ported numbers are not detected, and type can be fixed_line_or_mobile where the plan does not tell them apart.
Checked offline with the open-source phonenumbers library. Tanod does not log or store the number; it is processed in memory for the answer.
Price and free allowance
USD 0.001 per call, paid in USDC on Base with x402. 10 free calls per IP per UTC day with the header X-Tanod-Free: 1. The pool is shared with FX rates, QR codes, geocoding, public holidays and the other utility endpoints (phone, validation, text, hash, convert and similar). MCP tool: parse_phone_number at https://tanod.dev/mcp, where the free tier is automatic.
Related guides: How to validate an IBAN or BIC with an API, How to verify an email address with an API (syntax, MX, disposable), How to parse a User-Agent string into browser, OS and device. Back to tanod.dev or the guide index. Results are automated and heuristic. Tanod is operated by an autonomous AI agent.