Phone Number Validation & Formatter API

The Phone Validator API is supported in 242 countries.

The Phone Number Validation & Formatter API allows you to easily process phone numbers entered by users in a wide variety of formats. Whether the input is as irregular as 1(212)-867-53-09, +1 212 8675309, 001-212.867.5309, or simply 2128675309, our API will intelligently detect the structure and return a standardized version.

This tool automatically converts the given input into E.164 format, which is the globally recognized format for international phone numbers. For example, +1 212 867 5309 is returned as +12128675309, making it suitable for international calling systems and integrations.

Beyond formatting, the API provides detailed phone number validation capabilities. It checks whether the number is isValid: true — meaning it is a valid number according to national numbering plans. It also offers an isPossible: true check, which indicates whether a number could potentially exist even if it’s not currently assigned. This is useful for pre-validation before saving or processing.

The numberType parameter helps identify if the phone number is a mobile, landline, or VoIP number. This is especially useful in scenarios where you only want to allow mobile numbers for SMS verifications or landlines for office contacts.

With support for area code recognition, the API can also detect the number’s geographical origin. For example, a number starting with area code 212 is automatically mapped to New York City (Manhattan). This feature is perfect for applications that require location-based segmentation or analysis.

Each number is also associated with detailed country-level metadata, such as the ISO region code (e.g., US) and numeric country code (e.g., 1), enabling region-specific logic and display formats in your applications.

✅ API Response

Example JSON response:

{
  "status": true,
  "remaining_credits": 15709,
  "expires": 0,
  "duration": "18ms",
  "regionCode": "US",
  "countryCode": 1,
  "country":"Unites 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)"
}

Try the Phone Validation API Yourself

Basic Usage

Send a phone number to the following endpoint:

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309

You can get your daily free API key with 200 credits from this link.

Address Parameter

The API also supports an optional address parameter, which can be highly useful in cases where the phone number is provided without an international country code. This field helps the system detect the intended region and correctly parse the number. For example, if the input number is 2128675309 and no country code is specified, setting address=US, address=United States, or even address=New York can help the API determine that the number belongs to the United States.

The address parameter accepts input in multiple formats, including:

• ISO 3166-1 alpha-2 codes like US, DE, or TR
• Country names such as Germany, Turkey, or America
• City or region names like Berlin, Istanbul, or New York

Although optional, the address becomes mandatory if the phone number does not begin with a plus sign and an international dialing code (e.g., +1, +44, +90). Without this contextual information, the API may be unable to correctly interpret the national number format.

Example with address parameter:

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309&address=US

Response Fields

Number Type Values

curl "https://api.genderapi.io/api/phone?number=+49 151 12345678&address=United States&key=YOUR_API_KEY"

curl "https://api.genderapi.io/api/phone?number=%2B49%20151%2012345678&address=United%20States&key=YOUR_API_KEY"

Phone Validation API via POST Request

You can use the POST method to validate a phone number for the United States. Simply provide the phone number in E.164, national, or international format along with the country/address. Your API key must be sent as a Bearer token.

cURL Example

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"}'

PHP cURL Example

<?php
$url = "https://api.genderapi.io/api/phone";

$data = array(
    "number" => "+12128675309",
    "address" => "US"
);

$payload = json_encode($data);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "Authorization: Bearer YOUR_API_KEY"
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

JavaScript fetch Example

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"
  })
})
.then(response => response.json())
.then(data => console.log(data));

Python requests Example

import requests

url = "https://api.genderapi.io/api/phone"

payload = {
    "number": "+12128675309",
    "address": "United States"
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.post(url, headers=headers, json=payload)

print(response.json())

Client Libraries

To make integration even easier, we offer a range of official and community-supported client libraries for different programming languages. These libraries allow you to interact with the GenderAPI endpoints — like the Phone Number Validation API — without having to manually handle HTTP requests or JSON parsing. Simply choose the appropriate library for your environment, install it, and start making requests with minimal setup.

You can find the available client libraries and installation instructions at the following page:
https://www.genderapi.io/docs-client-libraries

Frequently Asked Questions (FAQ)

1. What is the Phone Number Validation & Formatter API?

The Phone Number Validation & Formatter API is a tool that allows you to validate, format, and analyze phone numbers from all over the world. It can convert numbers into the standardized E.164 format and determine metadata such as region, type (mobile/landline), validity, and more.

2. What is the Phone Number Validation used for?

It is used for checking whether a phone number is valid, formatting it for international usage, identifying the type of number (e.g., mobile, VoIP), detecting region-based metadata, and ensuring clean, standardized phone number input for CRM, marketing tools, or user signups.

3. How many countries are supported?

The API supports phone numbers from 242 countries and territories worldwide. This ensures global coverage for any international or regional application.

4. Which formats are supported?

The API accepts numbers in various formats such as national, international, or E.164. It automatically detects and normalizes them into the correct format.

5. What happens if I omit the country or address parameter?

If the phone number doesn't start with a '+' and no country/address is provided, the API may not be able to correctly interpret the number. Including the address parameter (like US, United States, or New York) is recommended.

6. Can the API detect the number type?

Yes. The API returns the numberType field which indicates if the number is a MOBILE, FIXED_LINE, VOIP, etc.

7. What’s the difference between isValid and isPossible?

isValid means the number is officially assigned and matches all regional rules. isPossible checks if the number could theoretically exist based on its structure, even if not yet assigned.

8. What kind of response does the API return?

A successful response includes status, formatted number variants (national, international, E.164), region data, number type, credit usage, and more. See the API Response example section for a full output example.

9. How should I send my API key?

For GET requests, append the key as ?key=YOUR_API_KEY. For POST requests, use the Bearer token in the header like this:
"Authorization: Bearer YOUR_API_KEY".

10. What if I see a status: false response?

This means the request failed. The message field will include a detailed error reason such as missing parameters, an invalid phone number, or insufficient credits.

11. Are special characters or spaces allowed in input?

Yes, but they must be URL-encoded for GET requests. For example, use %20 instead of a space. See the warning section above for correct usage.

12. Can I use addresses in different formats or languages?

Yes. In addition to ISO 3166-1 alpha-2 codes (like US, DE, TR), the address parameter also accepts full country names or city names — even in different languages. The API uses built-in AI to intelligently detect and interpret the correct country or region. For example:

address=Deutschland
address=États-Unis
address=İstanbul
address=New York
address=Estados Unidos

All of these inputs will be correctly mapped to their respective countries or regions by the API without any issues.