Phone Number Validation & Formatter API Documentation

Global phone intelligence

One number, consistent output

Accept national, international and irregularly formatted input, then receive standardized forms and validation metadata for 242 countries and territories.

Raw input+1 212 867 5309

E.164 output+12128675309

ValidationisValid and isPossible

FormattingNational, international and E.164

ClassificationMobile, landline, VoIP and more

LocationRegion, area code and place

Input parameters

Number and address context

Parameter	Requirement	Description
`number`	Required	Phone number in national, international or E.164 form.
`address`	Conditional	ISO country code, country name, city or region used to interpret a national number.

When address becomes required

If number does not begin with + and an international calling code, provide context such as US, United States or New York.

USGermanyİstanbulNew YorkÉtats-Unis

GET

Query-string authentication

Basic GET request

cURL

curl "https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=%2B12128675309&address=US"

URL encoding: Encode + as %2B and spaces as %20. Prefer your language’s URL/URLSearchParams utilities over manual string construction.

POST

Bearer authentication

Server-side POST request

Send the number and optional address as JSON, with the API key in the Authorization header.

cURL

curl -X POST "https://api.genderapi.io/api/phone" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"number":"+12128675309","address":"US"}'

JavaScript

const response = await fetch("https://api.genderapi.io/api/phone", {
  method: "POST", headers: { "Content-Type": "application/json", "Authorization": "Bearer YOUR_API_KEY" },
  body: JSON.stringify({ number: "+12128675309", address: "United States" })
});

API response

Validation, formatting and metadata

JSON

{
  "status": true, "remaining_credits": 15709, "expires": 0, "duration": "18ms",
  "regionCode": "US", "countryCode": 1, "country": "United States",
  "national": "(212) 867-5309", "international": "+1 212-867-5309", "e164": "+12128675309",
  "isValid": true, "isPossible": true, "numberType": "FIXED_LINE_OR_MOBILE",
  "nationalSignificantNumber": "2128675309", "rawInput": "+1 212 867 5309",
  "isGeographical": true, "areaCode": "212", "location": "New York City (Manhattan)"
}

Response fields

Field	Type	Description
`status`	boolean	Whether the request completed successfully.
`remaining_credits`	integer	Credits available after the request.
`expires`	integer	Credit expiration time as a UNIX timestamp.
`duration`	string	Server processing time.
`regionCode`	string	Detected ISO 3166-1 alpha-2 region code.
`countryCode`	integer	International dialing code.
`country`	string	Human-readable country name.
`national`	string	Number formatted for national use.
`international`	string	Number formatted for international display.
`e164`	string	Canonical E.164 representation.
`isValid`	boolean	Whether the number satisfies regional validation rules.
`isPossible`	boolean	Whether the number could exist based on its structure.
`numberType`	string	Detected number category.
`nationalSignificantNumber`	string	National number without the country calling code.
`rawInput`	string	Original number submitted in the request.
`isGeographical`	boolean	Whether the number can be associated with a geographic area.
`areaCode`	string	Detected area-code segment.
`location`	string	Location associated with the area code.

Classification reference

Number type values

FIXED_LINE

Landline tied to a geographic location.

MOBILE

Mobile or cellular number.

FIXED_LINE_OR_MOBILE

Numbering plan does not distinguish landline from mobile.

TOLL_FREE

Receiver-paid toll-free number.

PREMIUM_RATE

Premium-rate service number.

SHARED_COST

Call cost is shared by caller and recipient.

VOIP

Voice-over-IP telephone number.

PERSONAL_NUMBER

Personal number that can redirect to another line.

PAGER

Pager notification number.

UAN

Universal Access Number used as a shared business contact.

VOICEMAIL

Dedicated voicemail access number.

UNKNOWN

Number category could not be determined.

Common questions

Phone API FAQ

What does the phone validation API do?

It validates and normalizes phone numbers, returns national, international and E.164 formats, and identifies region, number type and geographic metadata when available.

What is the difference between isValid and isPossible?

isValid checks the number against regional numbering rules; isPossible indicates that its structure could represent a number, even when validity cannot be confirmed.

When is address required?

Provide address when the number does not begin with a plus sign and international calling code. It may be an ISO country code, country name, city or region.

How should special characters be sent?

URL-encode spaces, plus signs and other special characters in GET query parameters. JSON POST bodies are encoded by your HTTP client.

Next reference

Monitor usage and quota

Usage & quotaUnderstand credits and limits →Client librariesInstall a phone validation package →