Skip to main content

​
Endpoint

POST https://api.bunny.build/api/v1/phone-validation

​
Authentication

HeaderRequiredValue
X-API-KeyYesYour API key (bun_...)
Content-TypeYesapplication/json

​
Overview

Validate any phone number and retrieve structured metadata including country, calling code, and E.164 formatted output. The API normalizes the input number and identifies its country and national subscriber number, helping you reduce fraud, improve deliverability, and gate SMS flows on correctly formatted numbers.

​
Use cases

  • Validate phone numbers at sign-up to reduce fake accounts
  • Normalize international numbers to E.164 format
  • Identify the country and calling code for routing logic
  • Gate SMS flows on properly formatted phone numbers

​
Details

Accepts numbers in E.164 format (e.g. +14155552671). The number must include a leading + and country calling code. Spaces, dashes, dots, and parentheses are stripped automatically before parsing.

​
Request body

FieldTypeRequiredDescription
phonestringYesPhone number to validate (E.164 format, e.g. +14155552671)

​
Example

{
  "phone": "+14155552671"
}

​
Response

​
200 OK

FieldTypeDescription
phonestringOriginal phone number as submitted
validbooleanWhether the number is valid
e164stringE.164 formatted number
country_codestringISO 3166-1 alpha-2 country code (e.g. "US")
calling_codestringInternational calling code with leading + (e.g. "+1")
national_numberstringSubscriber number without the calling code
Example 
{
  "phone": "+14155552671",
  "valid": true,
  "e164": "+14155552671",
  "country_code": "US",
  "calling_code": "+1",
  "national_number": "4155552671"
}

​
401 Unauthorized

{
  "detail": "Missing API key. Include X-API-Key header."
}

​
402 Payment Required

{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}

​
422 Unprocessable Entity

{
  "detail": "Invalid or unparseable phone number"
}

​
429 Too Many Requests

{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}

​
cURL example

curl -X POST https://api.bunny.build/api/v1/phone-validation \
  -H "X-API-Key: bun_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+14155552671"}'