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)
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.
This service is not appropriate if you require an absolute indication that a telephone number is valid for 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.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. |
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:
|