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:
<InternationalExchangeInfoResponse xmlns="http://www.serviceobjects.com"> <InternationalExchangeInfo> <NumberIn>String content</NumberIn> <CountryCode>String content</CountryCode> <FormatNational>String content</FormatNational> <Extension>String content</Extension> <Locality>String content</Locality> <LocalityMatchLevel>String content</LocalityMatchLevel> <TimeZone>String content</TimeZone> <Latitude>String content</Latitude> <Longitude>String content</Longitude> <Country>String content</Country> <CountryISO2>String content</CountryISO2> <CountryISO3>String content</CountryISO3> <FormatInternational>String content</FormatInternational> <FormatE164>String content</FormatE164> <Carrier>String content</Carrier> <LineType>String content</LineType> <SMSAddress>String content</SMSAddress> <MMSAddress>String content</MMSAddress> <IsValid>true</IsValid> <IsValidForRegion>true</IsValidForRegion> <NoteCodes>String content</NoteCodes> <NoteDescriptions>String content</NoteDescriptions> </InternationalExchangeInfo> <Error> <Type>String content</Type> <TypeCode>String content</TypeCode> <Desc>String content</Desc> <DescCode>String content</DescCode> </Error> <Debug> <string xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">String content</string> <string xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">String content</string> </Debug> </InternationalExchangeInfoResponse>
Example of the response JSON body:
{
"InternationalExchangeInfo":{
"NumberIn":"String content",
"CountryCode":"String content",
"FormatNational":"String content",
"Extension":"String content",
"Locality":"String content",
"LocalityMatchLevel":"String content",
"TimeZone":"String content",
"Latitude":"String content",
"Longitude":"String content",
"Country":"String content",
"CountryISO2":"String content",
"CountryISO3":"String content",
"FormatInternational":"String content",
"FormatE164":"String content",
"Carrier":"String content",
"LineType":"String content",
"SMSAddress":"String content",
"MMSAddress":"String content",
"IsValid":true,
"IsValidForRegion":true,
"NoteCodes":"String content",
"NoteDescriptions":"String content"
},
"Error":{
"Type":"String content",
"TypeCode":"String content",
"Desc":"String content",
"DescCode":"String content"
},
"Debug":["String content"]
}
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.
