0151 355 4555

IsValid

Description

Checks a telephone number for validity. Details of the number's validity and other attributes are returned in a InternationalTelephoneValidationOutput structure.

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 and inexpensive method for preventing accidentally mis-typed numbers.

Options:

UseMobileValidation
If set to true then the service will use MobileValidation on any number it recognises as a mobile number and InternationalTelephoneValidation on all other numbers. Any validation call will be debited either an InternationalTelephoneValidation credit or a MobileValidation credit accordingly so please ensure you have MobileValidation credits available before using this option. The option defaults to false.

UseLineValidation
If set to true then the service will use LandlineValidation on any number it recognises as a UK landline number and InternationalTelephoneValidation on all other numbers. Any validation call will be debited either an InternationalTelephoneValidation credit or a LandlineValidation credit accordingly so please ensure you have LandlineValidation credits available before using this option. The option defaults to false.

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
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
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.

UseUnavailableStatus
When using the UseMobileValidation option and the mobile number is unavailable, this option causes the service to return Unavailable as the ValidationResult instead of the default Valid. This allows you to get additional insight into the status of the number.

TreatUnavailableMobileAsInvalid
When using the UseMobileValidation option and the mobile number is unavailable, this option causes the service to return Invalid as the ValidationResult instead of the default Valid. This will cause your calling application to have a stricter level of validation for mobiles, i.e. they must be turned on.

View all International Telephone Validation (Part of the phone validation suite) methods

Code Samples

<!-- Import the Integr8 Ajax API -->
<!-- NOTE: Get your own API key to use in the following script tag from: -->
<!-- http://www.data-8.co.uk/integr8/Admin/Ajax.aspx -->
<script src="https://webservices.data-8.co.uk/Javascript/Loader.ashx?key=your-api-key" type="text/javascript">
</script>

<script type="text/javascript">

function loadIntegr8() {
  // Load the InternationalTelephoneValidation Integr8 service
  data8.load('InternationalTelephoneValidation');
}

function IsValid(telephoneNumber, defaultCountry) {
  /// <param name="telephoneNumber">string</param>
  /// <param name="defaultCountry">string</param>
  var internationaltelephonevalidation = new data8.internationaltelephonevalidation();
  
  internationaltelephonevalidation.isvalid(
    telephoneNumber,
    defaultCountry,
    [
      new data8.option('UseMobileValidation', 'true'),
      new data8.option('UseLineValidation', 'true')
    ],
    showIsValidResult
  );
}

function showIsValidResult(result) {
  // Check that the call succeeded, and show the error message if there was a problem.
  if (!result.Status.Success) {
    alert('Error: ' + result.Status.ErrorMessage);
  }
  else {
    // TODO: Process method results here.
    // Results can be extracted from the following fields:
    // result.Result
  }
}

loadIntegr8();

</script>