Loading
Loading
Verify phone numbers and retrieve detailed metadata including carrier name, line type, geographic location, time zones, and standardized formats.
Send the phone number in the request body. The response includes validation status, carrier information, line type detection, location data, and four standardized formats (E.164, International, National, RFC3966).
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 the number field to validate:
{
"number": "+14155552671"
}numberrequiredStringPhone number to validate. Accepts international format (+923301112233), local format (03301112233) with region, or IDD format (00923301112233) with dialer_region.
regionoptionalStringTwo-letter ISO country code (e.g., US, GB). Required when number is in local format without a + prefix. Cannot be used together with dialer_region.
dialer_regionoptionalStringTwo-letter ISO country code of the dialing origin (e.g., AU, US). Required when number uses an IDD exit code. Cannot be used together with region.
A successful request returns a 200 OK response with a JSON object containing validation results.
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:
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.
The 'number' is required in Post Body and cannot be empty.
Provide the region explicitly (e.g. 'US') or include a '+' with the country code.
Provide only one region code, either 'region' or 'dialer_region', not both.
Region code must be a 2-letter ISO country code (e.g., 'US', 'GB').
The input does not match the expected structure of a phone number.
The number is too short after removing the international dialing prefix.
The national number part is shorter than allowed for valid phone numbers.
The phone number has more digits than any valid phone number can have.
Wrong HTTP method was used on the endpoint.
Timed out while connecting to the remote URL.