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:

Name	Type	Required?	Description
PhoneNumber	String	Yes	The 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.
Country	String	No	The 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.
LicenseKey	String	Yes	Your 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 Type	TypeCode
Authorization	1
User Input	2
Service Objects Fatal	3
Domain Specific	4

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:

Name	Type	Description
IsValid	Boolean	A boolean response type determining whether the phone number is a valid phone number.
IsValidForRegion	Boolean	A 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:

Name	Type	Description
PhoneNumberIn	String	The phone number that was provided as input.
CountryCode	String	The country code of the provided phone number.
FormatNational	String	The provided phone number in a national format.
Extension	String	The parsed extension from the provided phone number.
Locality	String	The locality from where the phone number belongs. The locality format is generally Locale/Region, Region or Country.
LocalityMatchLevel	String	The match level that was determined from the locality that was found. Possible values include (Locale/Region, Region, Country) match.
TimeZone	String	The Time Zone of the validated phone number.
Latitude	String	The latitude of the locality determined from the phone number.
Longitude	String	The longitude of the locality determined from the phone number.
Country	String	The country to which the validated phone number belongs.
CountryISO2	String	The ISO 2 character country designation for a validated phone number.
CountryISO3	String	The ISO 3 character country designation for a validated phone number.
FormatInternational	String	The provided phone number in international format.
FormatE164	String	The provided phone number in E.164 format.
LineType	String	The linetype determined for the phone number. See InternationalExchangeInfo LineType table.
SMSAddress	String	The SMS gateway address for the provided mobile number.
MMSAddress	String	The MMS gateway address for the provided mobile number.
IsValid	Boolean	A boolean response type determining whether the phone number is a valid phone number.
IsValidForRegion	Boolean	A boolean response type determining whether the phone number is a valid phone number for the provided Country.
NoteCodes	String	The corresponding codes which match NoteDescriptions. These values vary from 1 to 6 based on test results. See NoteCode table below.
NoteDescriptions	String	The 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.