IsValid
Checks if a telephone number is valid.
To connect to this service you'll need to use one of these endpoints:
Description
Checks a telephone number for validity and formats it in a standard format. Details of the number's validity and other attributes are included in the result.
The telephone number can be supplied as either a full international number with leading + or 00 prefix (e.g. +441513554555) or as a national number (e.g. 01513554555), with or without additional formatting (e.g. spaces, brackets etc.). If a number is supplied as a national number, the default country code is used to identify which country the number is located in. The default country code can be supplied as any of:
- international telephone dialling code (e.g. 44)
- ISO 2-character code (e.g. GB)
- ISO 3-character code (e.g. GBR)
- ISO standard English country name (e.g United Kingdom)
- "auto" to detect the country from the user's location (client-side integrations)
If the ValidationResult
member of the returned structure is Invalid
, the supplied telephone number is invalid and cannot be called. If it is Valid
the telephone number is likely to be valid. This does not necessarily mean that the number can be called and is owned by the expected person, but does indicate that the number lies within a range of numbers that have been allocated for use. If it is NoCoverage
we cannot provide an indication to it's validity and you should normally treat it as valid.
If you are using this API to prevent invalid telephone numbers in form submissions, we recommend only blocking `Invalid` results and allowing all other status codes.
This service is not appropriate if you require an absolute indication that a telephone number is related to a particular individual. In those circumstances, you should consider the use of a telephone number capture service. However, this service does provide a quick method to check that a number can accept incoming calls.
Wherever possible this method will perform a live check of the telephone network. This will be performed for UK landline numbers and international mobile numbers. The ValidationLevel
property in the response will be set to FullNumber
if a live check was performed.
070
, often referred to as personal numbers, are incredibly difficult to validate with any certainty, due to their private nature. We have created an option you can pass in to the API code, ExcludeUnlikelyNumbers
, which will stop the likes of 07000000000
or 07077777777
getting through our validation. Please bear in mind that with this option, you may well exclude a small amount of genuine numbers.Credit Usage
Each request to this method consumes 1 Phone Validation credit for each request, except where a "NoCoverage" result is returned. US mobile numbers are billed at 2 credits per request if the "IncludeUSStatus" option is set to true, or the default setting to enable this is turned on for your account.
Parameters
The following parameters can be supplied to this method
username |
username apikey- , e.g.
apikey-ABCD-1234-EFGH-5678
|
---|---|
password |
password |
telephoneNumber | telephoneNumber The telephone number to validate |
defaultCountry | defaultCountry The ISO 2-character country code or international dialling code of the country to validate the |
options | options |
Advanced Options
The following options can be specified as part of the option
parameter. Each option is specified
as a key/value pair. The list of available names is shown below, along with a description of the allowable values
for that name.
Common Options | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Name | Description | |||||||||||||||||||||
ApplicationName | ApplicationName Gives the name of the calling application - used to break down usage by application in the usage reports on the dashboard |
|||||||||||||||||||||
Service-Specific Options | ||||||||||||||||||||||
Name | Description | |||||||||||||||||||||
RequiredCountry | RequiredCountry Indicates the country that the number must be in to be considered valid. This should be provided as the ISO 2-character country code. |
|||||||||||||||||||||
AllowedPrefixes | AllowedPrefixes A comma-separated list of prefixes in standard international format that the number must start with to be treated as valid. For example, use "+441,+442" to allow only standard UK landline numbers. |
|||||||||||||||||||||
BarredPrefixes | BarredPrefixes A comma-separated list of prefixes in standard international format that will cause the number to be treated as invalid. For example, use "+90,+447781" to block any Indian numbers or numbers allocated to C&W Guernsey. |
|||||||||||||||||||||
TreatUnavailableMobileAsInvalid | TreatUnavailableMobileAsInvalid When validating a mobile number and the number is unavailable, this option causes the service to return |
|||||||||||||||||||||
ExcludeUnlikelyNumbers | ExcludeUnlikelyNumbers If set to |
|||||||||||||||||||||
DefaultFormatType | DefaultFormatType The format the telephone number should be returned in. This can be one of the following values:
|
|||||||||||||||||||||
DifferentFormatCountries | DifferentFormatCountries A comma-separated list of country codes (without leading + or 00). Any telephone numbers for these countries will be formatted using the |
|||||||||||||||||||||
DifferentFormatType | DifferentFormatType The format the telephone number should be returned in if it is from a country listed in |
|||||||||||||||||||||
UseLocalFormatting | UseLocalFormatting Indicates if telephone numbers should be formatted according to the country-specific rules for its particular country. If this is set to false, numbers are formatted according to ITU international standard formatting. |
|||||||||||||||||||||
EndUserIPAddress | EndUserIPAddress If the |
|||||||||||||||||||||
CustomFormatCountries | CustomFormatCountries The Formats are specified using the following special characters. Examples show the result of the formatting character based on the input telephone number +441513554555 extension 1234.
Any other characters will be treated as literal strings. The backslash character is used as an escape character, so If there are more numbers in the telephone number than are output by the specified format string, the additional numbers will be appended to the result to ensure no data is lost. |
|||||||||||||||||||||
IncludeUSStatus | IncludeUSStatus By default, all North American phone numbers will be validated to ensure the exchange is correct, i.e. all but the final 4 digits. Full number validation is available for US mobile numbers, but due to the costs involved in this process any such numbers are billed at 2 credits per lookup instead of the usual 1. Because of this difference in cost, this is an opt-in process. You can opt-in to this additional validation on a per-request basis using this option, or you can change your default setting on your dashboard. |
Results
This method returns an object containing the following fields:
Status |
Status Success field is true , the other results described below can be used to get the results of the method.
If Success is false , some error occurred in calling the method, such as the authentication failed or the
account is out of credits. The details of the error can be obtained from the ErrorMessage field, and any other results should be ignored
|
||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Result | Result Contains properties indicating the validity and other information for the supplied telephone number:
|