Posts Tagged ‘international phone exchange’

Beginner’s Guide to International Phone Exchange

Our DOTS Phone Exchange can validate both domestic and international phone numbers. In this article, we will focus on validating international phone numbers using the operation, GetInternationalExchangeInfo. This operation parses a given international phone number to determine the validity of its telephone exchange. The resulting outputs also include geographic location and carrier information when available. Use of this operation helps determine the overall validity of a phone number and returns a standardized format along with other information about the line-type. Many countries have distinct numbering plans, formats, and rules. This operation verifies that each number conforms to those rules and confirms regional validity. 

To get started, the following GetInternationalExchangeInfo inputs are recommended:

NameTypeRequired?Description
PhoneNumberStringYesThe phone number to be parsed, validated and formatted. The phone number may include extension as well. If no country is provided, the country code should be provided in the phone number.
CountryStringNoThe Country format to be validated using the provided phone number. Acceptable Country formats include ISO2 (preferred), ISO3, full country name, variant of full country name, and IP of the phone number’s collection region.
LicenseKeyStringYesYour license key to use the service.
Sign up for a free license key.

Although Country input is not required, we highly recommended it. The Country input helps the service validate the phone number according to the rules and format of the given country. Making it easier to parse the number and make possible corrections. Without the Country input, the service does its best to find a country that matches the given number; however, some countries share numbering plans and formats, which can lead to ambiguities.

Outputs from Phone Exchange

The operation output consists of a response container and three complex child objects:

Response Objects Container:

  • InternationalExchangeInfoResponse

Child Objects:

  • InternationalExchangeInfo – contains useful information about the number, such as line type, validity, and geographic location details. The developer guide includes a full list of output fields and descriptions. NOTE: If an Error object is returned, then expect this object to be null.
  • Error – returned if a problem occurs. Specific error types and descriptions are returned and handled accordingly.
  • Debug – primarily used for internal use by Service Objects, but in some special cases, a client request may enable it to help troubleshoot client-specific issues.

Below is an example of the response XML body:

Example of the response JSON body:

 

Handling the Response Output from Phone Exchange

When calling the service, first check for errors and handle them appropriately. There are four different error types, which are listed below.

Error TypeTypeCode
Authorization1
User Input2
Service Objects Fatal3
Domain Specific4

Please refer to the developer guide for a complete list of errors and their descriptions.

Error type 1: Authorization

Authorization errors indicate a problem with the given license key. License key expiration and exceeding maximum transaction threshold triggers Authorization errors. Authorization errors indicate a license key is no longer authorized to process transactions. These types of errors cannot be resolved on their own and require the license key owner to contact Service Objects to reauthorize their license key or increase their maximum transaction threshold. The most common Authorization errors occur when first integrating the service or when a user tries using the wrong license key.

Error type 2: User Input

User Input errors occur because of a wrong input, like a missing PhoneNumber or LicenseKey input value.

Error type 3: Service Objects Fatal

These errors occur when the service encounters an unexpected error that causes the application to fail. If you encounter a fatal error, please report it to Service Objects support team, along with any pertinent details, such as the request date and time, the operation name and the input values. Fatal errors should be infrequent, so please report them so that the support team can investigate and fix any potential issues.

Error type 4: Domain Specific

These errors show that despite successful processing of the request, a problem occurred. For example, a phone number entered with a missing a country code, or a value that does not appear to be a valid phone number. Most domain-specific errors for the GetInternationalExchangeInfo indicate a problem with the phone number and notifies the user that it is likely invalid. Refer to the developer guide for a list of domain-specific errors and be sure to handle each one appropriately.

InternationalExchangeInfo Object

If no errors are returned, then you may start using the InternationalExchangeInfo object to get details about the phone number, like country, locality and line type. We recommend first checking the following two output values before any others in the InternationalExchangeInfo object:

NameTypeDescription
IsValidBooleanA boolean response type determining whether the phone number is a valid phone number.
IsValidForRegionBooleanA boolean response type determining whether the phone number is a valid phone number for the provided Country.

If the phone number is found to be invalid, you can save yourself time by immediately rejecting it. If the number is valid, then start making use of the other output values as they pertain to your needs. The complete list of outputs can be seen below:

NameTypeDescription
PhoneNumberInStringThe phone number that was provided as input.
CountryCodeStringThe country code of the provided phone number.
FormatNationalStringThe provided phone number in a national format.
ExtensionStringThe parsed extension from the provided phone number.
LocalityStringThe locality from where the phone number belongs. The locality format is generally Locale/Region, Region or Country.
LocalityMatchLevelStringThe match level that was determined from the locality that was found. Possible values include (Locale/Region, Region, Country) match.
TimeZoneStringThe Time Zone of the validated phone number.
LatitudeStringThe latitude of the locality determined from the phone number.
LongitudeStringThe longitude of the locality determined from the phone number.
CountryStringThe country to which the validated phone number belongs.
CountryISO2StringThe ISO 2 character country designation for a validated phone number.
CountryISO3StringThe ISO 3 character country designation for a validated phone number.
FormatInternationalStringThe provided phone number in international format.
FormatE164StringThe provided phone number in E.164 format.
LineTypeStringThe linetype determined for the phone number. See InternationalExchangeInfo LineType table.
SMSAddressStringThe SMS gateway address for the provided mobile number.
MMSAddressStringThe MMS gateway address for the provided mobile number.
IsValidBooleanA boolean response type determining whether the phone number is a valid phone number.
IsValidForRegionBooleanA boolean response type determining whether the phone number is a valid phone number for the provided Country.
NoteCodesStringThe corresponding codes which match NoteDescriptions. These values vary from 1 to 6 based on test results. See NoteCode table below.
NoteDescriptionsStringThe corresponding descriptions which match NoteCodes. These values vary based on NoteCodes. See NoteCode table below.

Geographic information about a number is useful, as is knowing if the line type is mobile, fixed (landline) line or Voice Over IP (VOIP) line. As always, please refer to the developer guide for the complete list of outputs and descriptions.

When in doubt – reach out!

Hopefully, this overview provides a strong understanding of how you can use the operation, GetInternationalExchangeInfo, to validate and standardize international phone numbers. If you are looking to validate and standardize US and Canadian phone numbers, we recommend the GetExchangeInfo operation.

As always, our experienced staff is ready to help, so please do not hesitate to reach out. We would be happy to answer any questions and offer best practices for using our service.