Loading
Loading
Validate up to 100 phone numbers in a single request. Each number is independently checked and returns the same comprehensive data as single validation.
Send an array of phone number objects in the request body. Each object includes the number and optional region fields. Invalid entries do not affect the rest of the batch.
Pass your API key as the apiKey parameter in every request.
This is version v1.0 of the API.
The following optional query parameter controls the response format.
formatoptionalstringdefault: jsonResponse format. Possible values are:
The request body must be in JSON format and include a numbers array of phone number objects:
{
"numbers": [
{
"number": "+14155552671"
},
{
"number": "03301112233",
"region": "PK"
},
{
"number": "0014155552671",
"dialer_region": "AU"
}
]
}numbersrequiredArray<Object>Array of phone number objects to validate. Maximum 100 objects per request.
Each object in the numbers array supports the following fields:
{
"number": "+14155552671",
"region": "US",
"dialer_region": "AU"
}numberrequiredStringThe phone number to validate. Can include international prefix (+), local format, or IDD exit code format.
regionoptionalStringISO-2 country code (e.g., US, GB) for unambiguous parsing.
dialer_regionoptionalStringISO-2 country code of the dialing origin (e.g., AU, US).
A successful request returns a 200 OK response with an array of per-number validation results.
-Returns an array of phone validation objects, one per phone number submitted in the request.
Each object in the response array contains the following fields:
possibleWhether the number is possible (length and format checks only). A number can be possible but not valid.
validWhether the number is valid according to the numbering plan.
country_prefixThe international dialing prefix for the number's country (e.g., 1 for US/Canada, 44 for United Kingdom).
national_numberThe national significant number (the phone number without the country code).
country_codeISO-2 country code inferred from the number (e.g., US, GB).
carrierCarrier name associated with the number (if available). May not reflect ported carriers.
locationGeographic description (city/region) for the number (if applicable).
time_zonesArray of possible time zones associated with the number.
line_typeClassification of the phone line (MOBILE, FIXED_LINE, VOIP, etc.).
area_code_lengthLength of the geographic area code. Only applies to geographically-assigned numbers.
ndc_lengthLength of the National Destination Code (NDC), the routing prefix within a country.
can_be_internationally_dialledWhether the number can be dialled internationally. false for short codes, emergency numbers, and domestic-only services.
The raw_input object reflects the original request data for each number:
raw_input.numberThe phone number as entered by the user.
raw_input.regionISO-2 country code (e.g., US, GB). Present when provided in the request.
raw_input.dialer_regionISO-2 country code of the dialing origin. Present when provided in the request.
The formats object contains the number in four standardized representations (returned for valid numbers):
formats.E164Number in E.164 format, the standard machine-readable format used for storage and APIs. Example: +14155552671.
formats.InternationalHuman-readable international format with country code, spaces, and punctuation. Example: +1 415-555-2671.
formats.NationalLocal format as dialed within the country, without the country code. Example: (415) 555-2671.
formats.RFC3966URI format following RFC 3966, used for tel: links in HTML and SIP/VoIP applications. Example: tel:+1-415-555-2671.
All possible values for the line_type field:
MOBILEMobile or cellular number.
FIXED_LINEWired landline number.
FIXED_LINE_OR_MOBILECould be either. Some countries don't distinguish between the two.
VOIPVoice over IP number (e.g., Google Voice, Skype).
TOLL_FREEFree for the caller. Receiver pays (e.g., 1-800 numbers).
PREMIUM_RATECaller is charged above the normal rate.
SHARED_COSTCost is split between caller and receiver.
PERSONAL_NUMBERAssigned to a person, not a device. Can forward to any phone.
PAGERPaging device number.
UANUniversal Access Number. Routes to different destinations based on caller location.
VOICEMAILDedicated voicemail service number.
UNKNOWNType could not be determined.
The API uses standard HTTP status codes to indicate the success or failure of requests. For common status codes like 429 (Too Many Requests), refer to the general API documentation.
Please provide data in required format in request body
Missing Number - The 'number' is required in Post Body and cannot be empty.
Missing Region Information - Provide the region explicitly (e.g. 'US') or include a '+' with the country code.
Invalid Number Format - The input does not match the expected structure of a phone number.
Number Too Short - The number is too short after removing the international dialing prefix.
Too Short National Number - The national number part is shorter than allowed for valid phone numbers.
Number Too Long - The phone number has more digits than any valid phone number can have.
Invalid Region Code - Region code must be a 2-letter ISO country code (e.g., 'US', 'GB').
Multiple Region Codes Provided - Only one of 'region' or 'dialer_region' can be provided. Do not use both in the same request.
Wrong HTTP method was used on the endpoint.
Timed out while connecting to the remote URL.