• Introduction
• Integration
  • Code Snippets
• Request Types
• Operation Definitions
  • GetSMSInfo
  • GetExchangeInfo
  • GetExchangeInfo_V2
• Errors
• Frequently Asked Questions
• Conclusion

Introduction

DOTS Phone Exchange is an XML web service that provides information about telephone numbers. With DOTS Phone Exchange users can verify telephone numbers, receive geographic location and carrier information of any phone number in the U.S.

Integration

Integration of DOTS Phone Exchange into user applications is generally a straightforward process. For common programming platforms, such as ASP, ASP.NET, ColdFusion, PHP, etc., Service Objects will likely have sample code available online:
https://www.serviceobjects.com/sample-code/?service=79

If the code you seek is not available online, you can ask Service Objects to build a custom example for you. Email support@serviceobjects.com for more details.

Web Service Structure

Web services provide a standard interface to encapsulate tricky business logic. They allow simple integration of applications via the web. Service Objects has followed web services best practices and come up with some of its own standards to ensure that its web services are as easy to integrate, and as accessible as possible.

The host path, or physical location of the web service is here:
https://trial.serviceobjects.com/pe/PhoneExchange.asmx

The location of the WSDL, or Web Service Definition Language document, is here (This is also accessible via the “Service Definition” link on the web service page.):
https://trial.serviceobjects.com/pe/PhoneExchange.asmx?WSDL

The WSDL is an XML document that defines the interaction web service, meaning its inputs, outputs, operations, and the like. Most likely, you will have another tool read this WSDL and make the operations available to you in your application via some type of proxy class. Whenever your utilities or IDE asks for a WSDL path, you can provide this one.

Every web service has operations that it offers to subscribers. These operations, also called methods, contain different functionality and return different outputs. DOTS Phone Exchange has the following operations: 

GetSMSInfo – Uses the provided phone numbers to return geographic location, carrier information, and sms domain information of any mobile phone number in the U.S. 
GetExchangeInfo – Uses the provided phone numbers to return geographic location and carrier information of any phone number in the U.S. 
GetExchangeInfo_V2 – This operation is similar to GetExchangeInfo, but also returns VOIP as a possible line type. 

Each of these operations will be described in detail later in this document.

Code Snippets

//Add a service to your application https://trial.serviceobjects.com/rest/pe/api.svc
PEClient_Primary = new PELibraryClient("DOTSPE");
response = PEClient_Primary.GetExchangeInfo_V2(number, licenseKey);
         
if (response.Error != null)
{
    //Process Error
}
else
{
    //Process Response     
}

ExchangeInfo_V2Response resp = null;
ExchangeInfo_V2Result result = null;
PEError error = null;
// Create soap request
PELibraryLocator locator = new PELibraryLocator();
// use ssl
locator.setsoapEndpointAddress("https://trial.serviceobjects.com/rest/pe/api.svc/soap");
IPELibrary pe = locator.getsoap();
SoapStub soap = (SoapStub) pe;
soap.setTimeout(5000);// set timeout
resp = soap.getExchangeInfo_V2(phoneNumbers, key);
result = resp.getPhoneExchangeInfo();
error = resp.getError();
if(resp == null || (error != null && error.getTypeCode() == "3"))
{
    throw new Exception();
}
  
//Process Results
if(error == null){
    //DOTS Phone Exchange Results  
}
//Process Errors
else{
    //DOTS Phone Exchange Error Results
}

<?php
// Set these values per web service <as needed>
$wsdlUrl = "https://trial.serviceobjects.com/rest/pe/api.svc?wsdl";
 
$params['phoneNumber'] = $PhoneNumber;
$params['LicenseKey'] = $LicenseKey;
 
$soapClient = new SoapClient($wsdlUrl, array( "trace" => 1 ));
$result = $soapClient->getExchangeInfo_V2($params);
if (!isset($result->ExchangeInfo_V2Response ->Error)) {
    foreach($result->ExchangeInfo_V2Response ->PhoneExchangeInfoas $k=>$v) {
        echo $k . ", " . $v;
    }
} else {
    foreach($result->ExchangeInfo_V2Response ->Error as $k=>$v) {
        echo $k . ", " . $v;
    }
}
?>

using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;
namespace DOTSPhoneExchange
{
    public partial class _Default : System.Web.UI.Page
    {
        private com.serviceobjects.trial.DOTSPhoneExchange DOTSPhoneExchange;
        private com.serviceobjects.trial.ExchangeInfo exchangeInfo;
        private com.serviceobjects.trial.Providers providers;
 
        protected void Page_Load(object sender, EventArgs e)
        {
            DOTSPhoneExchange = new com.serviceobjects.trial.DOTSPhoneExchange();
            exchangeInfo = null;
            providers = null;
            ResultLabel.Visible = false;
        }
        protected void btn_GO_Click(object sender, EventArgs e)
        {
            try
            {
                // Call DOTS Phone Exchange service using GetExchangeInfo_V2 service
                exchangeInfo = DOTSPhoneExchange.GetExchangeInfo_V2(inputPhoneNumber.Text, inputLicenseKey.Text);
 
                DataTable dtProvider = new DataTable();
                DataTable dtError = new DataTable();
                /*declaring a table to hold the provider information*/
                dtProvider.Columns.Add(new DataColumn("Output", typeof(string)));
                dtProvider.Columns.Add(new DataColumn("Values", typeof(string)));
                 
                if (exchangeInfo.Error != null)
                {
                    // If DOTS Phone Exchange returns any errors capture them and output here
                    dtError.Columns.Add(new DataColumn("Output", typeof(string)));
                    dtError.Columns.Add(new DataColumn("Values", typeof(string)));
                    dtError.Rows.Add("Error", exchangeInfo.Error.Desc);
                    dataGrid1.Visible = false;
                    dataGrid2.DataSource = new DataView(dtError);
                    dataGrid2.DataBind();
                }
                else
                {   // No errors found. Return info from providers
                    providers = exchangeInfo.Providers;
                    int providerCount = 1;
                    foreach (com.serviceobjects.trial.Provider provider in providers.Provider)
                    {
                        // Add provider info to result datagrid
                        dtProvider.Rows.Add("<b>Provider #" + providerCount + "</b>");
                        dtProvider.Rows.Add("Phone Number", provider.PhoneNumber);
                        dtProvider.Rows.Add("Name", provider.Name);
                        dtProvider.Rows.Add("City", provider.City);
                        dtProvider.Rows.Add("State", provider.State);
                        dtProvider.Rows.Add("Line Type", provider.LineType);
                        dtProvider.Rows.Add("Latitude", provider.Latitude);
                        dtProvider.Rows.Add("Longitude", provider.Longitude);
                        if (provider.NumberErrorCode != null) {
                            dtProvider.Rows.Add("Number Error Code ", provider.NumberErrorCode);
                        }
                        if (provider.NumberErrorStatus != null)
                        {
                            dtProvider.Rows.Add("Number Error Status ", provider.NumberErrorStatus);
                        }
                        providerCount++;
                    };
                     
                    dataGrid1.Visible = true;
                    dataGrid2.Visible = false;
                    dataGrid1.DataSource = new DataView(dtProvider);
                    dataGrid1.DataBind();
 
                }//end if IPResult.Error != null
            }
            catch (Exception ex)
            {   // Catch any errors while callling DOTS Services and output them to ResultLabel
                ResultLabel.Text = ex.Message;
                ResultLabel.Visible = true;
            }
        }
    }
}

XML Request: 
https://trial.serviceobjects.com/pe/PhoneExchange.asmx/GetSMSInfo?PhoneNumbers=8059612034+ext.+4321&LicenseKey=licenseKey

<SMSInfoResponse xmlns="https://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<SMSInfo>
<SMSInfoResult>
<PhoneNumber>8059612034</PhoneNumber>
<Name>VERIZON CALIFORNIA INC.-CA (GTE)</Name>
<City>GOLETA</City>
<State>CALIFORNIA</State>
<LineType>LANDLINE</LineType>
<Latitude>34.4599</Latitude>
<Longitude>-119.936</Longitude>
<SMSDomain/>
<SMSEmail/>
</SMSInfoResult>
</SMSInfo>
</SMSInfoResponse>

XML Request: 
https://trial.serviceobjects.com/pe/PhoneExchange.asmx/GetExchangeInfo_V2?PhoneNumbers=8059612034+ext.+4321&LicenseKey=licenseKey

<ExchangeInfo_V2Response xmlns="https://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<PhoneExchangeInfo>
<ExchangeInfo_V2Result>
<PhoneNumber>8059612034</PhoneNumber>
<Name>VERIZON CALIFORNIA INC.-CA (GTE)</Name>
<City>GOLETA</City>
<State>CALIFORNIA</State>
<LineType>LANDLINE</LineType>
<Latitude>34.4599</Latitude>
<Longitude>-119.936</Longitude>
</ExchangeInfo_V2Result>
</PhoneExchangeInfo>
</ExchangeInfo_V2Response>

Request Types

DOTS Phone Exchange is a public XML web service that supports SOAP(1.1 and 1.2), POST, and GET request methods. A request type is just the type of web (HTTP) request used to interact with our web services. 
GET – All of the input data is in the query string appended to the URL. The response is simple XML. 
POST – The input parameters are in the body of the request instead of the query string. The response is simple XML. 
SOAP – The input parameters are in an XML SOAP message contained within the body of the request. The response is an XML SOAP message.

Analysis of Request Types

GET is the easiest method to implement by hand because you just set up the URL and query string. It is also easy to debug because you can test the URL + query string in a web browser and see the output. 
POST is probably the best method to implement by hand because you do not have to know the specifics of SOAP, and is a little cleaner than passing input parameters in the query string via GET. 
SOAP is the best method if you are using a platform that supports SOAP. In many programming environments you can call the service’s WSDL file (https://trial.serviceobjects.com/pe/PhoneExchange.asmx?WSDL) to create a proxy class to help you interact with the web service. In this case you only have to create an instance of the proxy and use its methods. This completely abstracts the programmer from any complications like sending/receiving web requests/responses as well as any XML parsing. This is typically available in newer environments like PHP version 5, ColdFusion version 7, .NET, etc. Older languages like PHP version 4 and ColdFusion version 5 will require the use of GET or POST.

XML Parsing

If you are not using an environment that provides a proxy class for you to use, then you will have to parse XML. If you do have a proxy, then it uses an XML parser behind the scenes for you. Although XML parsing can be done without a parser, most programming environments provide easy access to several standard ones. We strongly recommend that you take advantage of an XML parser. These parsers may take a few more minutes to integrate if the developer is not familiar with them, but will give your application an added level of security against improper parsing. Without them it is very difficult, even for skilled programmers to write robust code that can handle all cases of XML properly. Because we have very consistent XML you could get away without this extra precaution, but we suggest you use an XML parser anyway to ensure your application is of the highest quality.

Operation Definitions

This section defines the input, output and behavior of the operations in DOTS Phone Exchange.

GetSMSInfo

Returns the geographic location and carrier of the US phone number(s) along with SMS contact information for wireless numbers. This operation is capable of processing multiple phone number transactions in a single request when the phone numbers are separated by a comma.

GetSMSInfo Inputs

GetSMSInfo Outputs

If no errors are encountered a SMSExchangeInfo element will be returned with the following information. If there is an error, an Error object will be returned (explained in next section).

GetExchangeInfo

Returns the geographic location and carrier of the US phone number(s). This operation is capable of processing multiple phone number transactions in a single request when the phone numbers are separated by a comma.

GetExchangeInfo Inputs

GetExchangeInfo Outputs

If no errors are encountered an ExchangeInfo element will be returned with the following information in a provider element. If a 6 digit (area code + suffix) number match is found then multiple provider elements within the ExchangeInfo element will be returned. If there is an error, an Error object will be returned (explained in next section).

GetExchangeInfo_V2

Returns the geographic location and carrier of the US phone number(s). This operation is capable of processing multiple phone number transactions in a single request when the phone numbers are separated by a comma. GetExchangeInfo_V2 adds the capability to return VOIP as LineType.

GetExchangeInfo_V2 Inputs

GetExchangeInfo_V2 Outputs

If no errors are encountered an ExchangeInfo element will be returned with the following information in a provider element. If a 6 digit (area code + suffix) number match is found then multiple provider elements within the ExchangeInfo element will be returned. If there is an error, an Error object will be returned (explained in next section).

Errors

Error codes in Phone Exchange are the same for all operations. They are as follows:

Error Code 1 – “Input cannot be less than zero length”

This error means the web service did not get any input. The connection to the service was made, and data was transferred, but no parameters were passed that the service could understand. 
This error often happens when input is passed to the service with namespaces that the service does not understand. Applying a namespace to any of the parameters (PhoneNumbers or LicenseKey, in this service) will cause this error. Additionally, requests made in the “rpc/encoded” format will cause this error. The only namespace that should appear in any element is the “https://www.serviceobjects.com” namespace on the root element as so: 
<GetExchangeInfo xmlns=”https://www.serviceobjects.com/“>

Error Code 2 – Various descriptions

This error code appears when various errors occur, but are of the expected nature. The most common occurrence is when there is no business contact listing found. Additionally, maligned or incomplete input will cause an error 2. Again, check the Error’s Desc element for the exact error.

Failed Authentication Errors:

• “Please provide a valid license key for this web service.”
• “The daily allowable number of transactions for this license key has been exceeded.”
• “The monthly allowable number of transactions for this license key has been exceeded.”
• “The total allowable number of transactions for this license key has been exceeded.”
• “There are not enough transactions available. Check your daily/monthly transaction limits.”
• “This license key has expired.”
• “This license key has not yet been activated.”
• “This operation is limited to specific usage. Please contact customer service to have your key enabled.”
• “Your license key does not work on this service.”

Web Service Invocation Errors:

• “Error initializing service”
• “Please input a valid 10 digit phone number.”

Error Code 3/4/5 – Various descriptions

An error code 4 is a fatal error and it means something has seriously gone wrong. You should never see an error code 4 in a live production environment.

Frequently Asked Questions

Can Phone Exchange give me information for Canadian phone numbers?

Yes. Phone Exchange can verify the telco exchange of any telephone number combination in the North American Numbering Plan.

Phone Exchange doesn’t find any data for my phone number!

You may have mistyped your phone number. A valid phone number will always return exchange information, whether it is wireless or landline, connected or disconnected. If you are certain that the number is valid and that it is part of the North American Numbering Plan, then please let us know at support@serviceobjects.com.

Why does Phone Exchange accept a 6 digit number?

When a single provider match is not enough, providing a 6 digit (area code + suffix) number will return a list of known providers that can be used for custom logic. If multiple provider matches for a 6 digit number are potentially problematic for your use case, then a simple solution is to check the length of the number before calling the Phone Exchange service and rejecting any numbers that are not 10 digits in length.

The Sample Code is Giving Strange Errors or is Crashing!

Most likely, the sample code cannot connect to ServiceObjects. Many environments will not allow you to connect out on port 80, or will clip out XML data from these requests/responses. 

The easiest way to check for this is to open a browser on the machine running the sample code. In your browser, navigate to: 
https://trial.serviceobjects.com/pe/PhoneExchange.asmx
Then try to run one of the operations with your trial key. If you get a browser error, or get no data back, then the sample code isn’t able to connect, either. Contact your systems administrator to resolve why you are not able to connect to Service Objects.

Do you also provide a RESTful interface?

Yes we do! For more information on how to use our RESTful interface go here DOTS Phone Exchange – REST.

Conclusion

Service Objects is proud to offer you a free trial of DOTS Phone Exchange.

Sign up today for a free trial at:
https://www.serviceobjects.com/phone-insight/?phone-exchange
Other technical questions or concerns can be directed to support@serviceobjects.com.

If you are interested in purchasing DOTS Phone Exchange, please contact sales@serviceobjects.com.

We welcome your feedback! Please do not hesitate to let us know what you think of our web services, documentation, or customer support.
www.serviceobjects.com