Skip to content
POST AI agent ready /v1/phone

Phone Validation API - Free Number Parser

Parses and validates a phone number. Returns formatted versions (E.164, national), country code, and country name.

Parameters

stringrequired

Phone number to validate. Include the country code for best results.

string

ISO 3166-1 alpha-2 country code hint for parsing numbers without a country prefix.

Code examples

curl -X POST https://api.botoi.com/v1/phone \
  -H "Content-Type: application/json" \
  -d '{"phone":"+14155552671","country":"US"}'

When to use this API

Normalize phone numbers in a contact database

Users enter phone numbers in dozens of formats: "415-555-2671", "(415) 555 2671", "+1 415.555.2671". Parse each one through this endpoint to get the standardized E.164 format for storage. Use the national_format for display in the UI.

Route SMS messages by country

Before sending an SMS through your messaging provider, validate the phone number and extract its country code. Route messages through region-specific SMS gateways to reduce costs and improve delivery rates.

Block invalid numbers in signup forms

Validate phone numbers on registration form submission. Reject invalid numbers immediately and show users the national format as a confirmation of what was parsed, catching typos before they reach your database.

Frequently asked questions

What phone number formats are accepted?
The endpoint accepts international format (+14155552671), national format ((415) 555-2671), and most common variations with dashes, dots, or spaces. Including the country code prefix gives the most accurate results.
When should I use the country parameter?
Use the country parameter when the phone number does not include a country code prefix (e.g. "4155552671" without "+1"). The country hint tells the parser which numbering plan to apply.
What is E.164 format?
E.164 is the international standard for phone numbers. It starts with a "+" followed by the country code and subscriber number, with no spaces or punctuation. Example: +14155552671.
Does this verify that the phone number is in service?
No. This endpoint validates format and structure only. It does not call or text the number to verify it is active.
Can I validate landline and mobile numbers?
Yes. The parser handles both landline and mobile number formats. It validates based on the country's numbering plan rules.

Get your API key

Free tier includes 5 requests per minute with no credit card required. Upgrade for higher limits.

Sign up free View full docs