Page tree
Skip to end of metadata
Go to start of metadata


Introduction


DOTS Phone Append 2 is an XML web service that provides information about landline telephone numbers. By providing contact name or business name and address information, DOTS Phone Append 2 provides the landline telephone number registered to the supplied information.

With Phone Append 2, users append telephone numbers to existing contact information. This information can be used to improve online applications or as supplemental information for existing databases.

If you are an existing client and are using the previous version of this service then please click on the following link.

DOTS Phone Append

Integration


Integration of DOTS Phone Append 2 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/developers/sample-code/phone-append

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/pa2/api.svc

The location of the WSDL, or Web Service Definition Language document, is here:
https://trial.serviceobjects.com/pa2/api.svc?WSDL

(This is also accessible via the "Service Definition" link on the web service page.) 
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 Append 2 has the operations listed below.

Code Snippets




Phone Append 2 C# Code Snippet
//Add a service to your application https://trial.serviceobjects.com/pa2/api.svc/soap
PhoneAppend2Client PA2Client_Primary = new PhoneAppend2Client("DOTSPA2");
PhoneInfoResponse response = PA2Client_Primary.CompositePhoneAppend(inputName, inputAddress, inputCity, inputState, inputZip, inputIsBusiness, inputLicenseKey);
		
if (response.Error != null)
{
	//Process Error
}
else
{
	//Process Response		
}


Phone Append 2 Java Code Snippet
Location location= null;

Err error = null;
// Create soap request
PhoneAppend2Locator locator = new PhoneAppend2Locatorlocator();
// use ssl
locator.setDOTSPhoneAppend2EndpointAddress("https://trial.serviceobjects.com/pa2/api.svc/soap");
IPhoneAppend2 pa= locator.getDOTSPhoneAppend2();
DOTSPhoneAppend2Stub soap = (DOTSPhoneAppend2Stub) pa;
soap.setTimeout(5000);
location= soap.phoneAppend_GETXML(fullName, firstName, lastName, address, city, state, postalCode, licenseKey);

error = location.getError();
if(resp == null || (error != null && error.getTypeCode() == "3"))
{
	throw new Exception();
}
 
//Process Results
if(error == null){
	//DOTS Phone Append 2 Results	
}
//Process Errors
else{
	//DOTS Phone Append 2 Error Results	
}


Phone Append 2 PHP Code Snippets
<?php
// Set these values per web service <as needed>
$wsdlUrl = "https://trial.serviceobjects.com/pa2/api.svc?wsdl";

$params['Name'] 		= $Name;
$params['Address'] 		= $Address;
$params['City'] 		= $City;
$params['State'] 		= $State;
$params['PostalCode'] 	= $PostalCode;
$params['isBusiness'] 	= $isBusiness;
$params['LicenseKey'] 	= $LicenseKey;

$soapClient = new SoapClient($wsdlUrl, array( "trace" => 1 ));
$result = $soapClient->CompositePhoneAppend($params);
if (!isset($result->CompositePhoneAppendResult->Error)) {
	foreach($result->CompositePhoneAppendResult->PhoneInfoas $k=>$v) {
		echo $k . ", " . $v;
	}
} else {
	foreach($result->CompositePhoneAppendResult->Error as $k=>$v) {
		echo $k . ", " . $v;
	}
}
?>


Phone Append 2 RoR Code Snippets
		#Formats inputs into a hash to pass to Soap Client
		#Hash Keys must be named as they are shown here.
		message = 	{
					"FullName" => @request.fullname,
					"FirstName" => @request.firstname,
					"LastName" => @request.lastname,
					"Address" => @request.address,
					"City" => @request.city,
					"State" => @request.state,
					"PostalCode" => @request.postalcode,
					"LicenseKey" => @request.licensekey,
					}

		#Implemented to make the code more readable when accessing the hash			
		@pa2response = :phone_append_response
		@pa2result = :phone_append_result
		@pa2info = :phone_info
		@pa2error = :error

		#Set Primary and Backup URLs here as needed
		dotsPA2Primary = "http://trial.serviceobjects.com/pa2/api.svc?WSDL"
		dotsPA2Backup = "http://trial.serviceobjects.com/pa2/api.svc?WSDL"

		begin
			#initializes the soap client. The convert request keys global is necessary to receive a response from the service.
			client = Savon.client(wsdl: dotsPA2Primary)
			#Calls the operation with given inptus and converts response to a hash.
			response = client.call(:phone_append, message: message).to_hash

			#Checks to see what results came back from the service
			processresults(response)			
			
		#If an error occurs during the call, this will use backup url and attempt to retrieve data.
		rescue Savon::Error => e
			begin
			backupclient = Savon.client(wsdl: dotsPA2Backup)
			#Sets the response to the backclient call to the operation and converts response to a hash.
			response = backupclient.call(:phone_append, message: message).to_hash
			processresults(response)
			#If backup url failed, this will display the error received from the server
			rescue Savon::Error =>error
			end
		end
	end
	private 
	def processresults(response)	
			#Processes Error Response from soap Client		
			#Processes Valid response from soap client	
	end


Phone Append 2 Python Code Snippet
    mFullName =  FullName.get()
    if mFullName is None or  mFullName == "":
        mFullName = " "
    mFirstName =  FirstName.get()
    if mFirstName is None or  mFirstName == "":
        mFirstName = " "
    mLastName =  LastName.get()
    if mLastName is None or  mLastName == "":
        mLastName = " "
    mAddress =  Address.get()
    if mAddress is None or  mAddress == "":
        mAddress = " "
    mCity = City.get()
    if mCity is None or mCity == "":
        mCity = " "
    mState = State.get()
    if mState is None or mState == "":
        mState = " "
    mPostalCode = PostalCode.get()
    if mPostalCode is None or mPostalCode == "":
        mPostalCode = " "
    mLicenseKey = LicenseKey.get()
    if mLicenseKey is None or mLicenseKey == "":
        mLicenseKey = " "

    #Set the primary and backup URLs as needed
    primaryURL = 'http://trial.serviceobjects.com/pa2/api.svc?WSDL'
    backupURL = 'http://trial.serviceobjects.com/pa2/api.svc?WSDL'

    #This block of code calls the web service and prints the resulting values to the screen
    try:
        client = Client(primaryURL)
        result = client.service.PhoneAppend(FullName= mFullName, FirstName= mFirstName, LastName=mLastName, Address= mAddress, City= mCity, State= mState, PostalCode= mPostalCode, LicenseKey= mLicenseKey)
        #Handel response and check for errors

    #Tries the backup URL if the primary URL failed
    except:
        try:
            client = Client(backupURL)
            result = client.service.PhoneAppend(FullName= mFullName, FirstName= mFirstName, LastName=mLastName, Address= mAddress, City= mCity, State= mState, PostalCode= mPostalCode, LicenseKey= mLicenseKey)
            #Handel response and check for errors

        #If the backup call failed then this will display an error to the screen
        except:
            Label(swin.window, text='Error').pack()
            print (result)


Phone Append 2 ColdFusion Snippet
<!--Makes Request to web service --->
<cfscript>
	try
	{
		if (isDefined("form.Action") AND Action neq "")
		{
			wsresponse = CreateObject("webservice", "http://trial.serviceobjects.com/pa2/api.svc?WSDL");							  
			outputs = wsresponse.phoneAppend("#FullName#", "#FirstName#", "#LastName#", "#Address#", "#City#", "#State#", "#PostalCode#" ,"#LicenseKey#");
			writedump(outputs.getPhoneInfo());
		}
	}
	catch(any Exception)
	{
		try
			{
				if (isDefined("form.Action") AND Action neq "")
				{
					wsresponse = CreateObject("webservice", "http://trial.serviceobjects.com/pa2/api.svc?WSDL");							  
					outputs = wsresponse.phoneAppend("#FullName#", "#FirstName#", "#LastName#", "#Address#", "#City#", "#State#", "#PostalCode#" ,"#LicenseKey#");
				}
			}
			catch(any Exception)	
				{
		  		 writeoutput("An Error Has Occured. Please Reload and try again #Exception.message#");		  		 
		 		}
	 }
</cfscript>


Phone Append 2 VB Snippet
Try
    Dim ws As New PA2.PhoneAppend2Client
    Dim response As PA2.PhoneInfoResponse

    response = ws.PhoneAppend(FullName.Text, FirstName.Text, LastName.Text, Address.Text, City.Text, State.Text, PostalCode.Text, LicenseKey.Text)
    If (response.Error Is Nothing) Then
        ProcessValidResponse(response)
    Else
        ProcessErrorResponse(response.Error)
    End If

Catch er As Exception
    Try
        ''Set the primary and backup service references as necessary
        Dim wsbackup As New PA2.PhoneAppend2Client
        Dim response As PA2.PhoneInfoResponse
        response = wsbackup.PhoneAppend(FullName.Text, FirstName.Text, LastName.Text, Address.Text, City.Text, State.Text, PostalCode.Text, LicenseKey.Text)
        If (response.Error Is Nothing) Then
            ProcessValidResponse(response)
        Else
            ProcessErrorResponse(response.Error)
        End If
    Catch ex As Exception
        resultsLabel.Visible = True
        resultsLabel.Text = ex.Message
    End Try
End Try


Phone Append 2 Apex Code Snippet
wwwServiceobjectsCom.PhoneInfoResponse result;
try{
wwwServiceobjectsCom.soap client = new wwwServiceobjectsCom.soap();
result = client.PhoneAppend([FullName], [FirstName], [LastName], [Address], [City], [State, [ZipCode], [LicenseKey]);
}
catch(Exception ex){
 //If the first request failed try the failover endpoint
wwwServiceobjectsCom.soap backupClient = new wwwServiceobjectsCom.soap();
//The backup environment will be provided to you upon purchasing a production license key
backupClient.endpoint_x = 'http://trial.serviceobjects.com/PA2/api.svc/soap';
result = backupClient.PhoneAppend([FullName], [FirstName], [LastName], [Address], [City], [State, [ZipCode], [LicenseKey]);
}


Phone Append 2 TSQL Code Snippet
SET @requestBody = '<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">' +
					'<s:Body>' +
					'<PhoneAppend xmlns="http://www.serviceobjects.com">' +
					'<FullName>' + @fullname  +  '</FullName>' +
					'<FirstName>' + @firstname  +  '</FirstName>' +
					'<LastName>' + @lastname  +  '</LastName>' +
					'<Address>' + @address  +  '</Address>' +
					'<City>' + @city  +  '</City>' +
					'<State>' + @state  +  '</State>' +
					'<PostalCode>' + @postalcode  +  '</PostalCode>' +
					'<LicenseKey>' + @key  +  '</LicenseKey>' +
					'</PhoneAppend>' +
					'</s:Body>' +
					'</s:Envelope>'
SET @requestLength = LEN(@requestBody)
	--If a production key is purchased, this will execute the failover 
IF @isLiveKey = 1
BEGIN
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'http://ws.serviceobjects.com/PA2/api.svc/soap', false
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'ws.serviceobjects.com'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Type', 'text/xml; charset=UTF-8'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'SOAPAction', '"http://www.serviceobjects.com/IPhoneAppend2/PhoneAppend"'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
	EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
	EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
	EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'http://wsbackup.serviceobjects.com/PA2/api.svc/soap', false
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'wsbackup.serviceobjects.com'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Type', 'text/xml; charset=UTF-8'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'SOAPAction', '"http://www.serviceobjects.com/IPhoneAppend2/PhoneAppend"'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
		EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
		EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
		EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
		EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
	END
END



Phone Append 2 C# Rest Code Snippet
string mainURL = WEB_SERVICE_PRIMARY_URL + state + "/" + city + "/" + postalcode + "/" + address + "/" + name + "/" + isbusiness + "/" + licensekey + "?format=json";
PA2Response result = null;
 
HttpWebRequest request = WebRequest.Create(mainURL ) as HttpWebRequest;
request.Timeout = 5000;//timeout for get operation
using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
{
	if (response.StatusCode != HttpStatusCode.OK)
		throw new Exception(String.Format(
		"Server error (HTTP {0}: {1}).",
		response.StatusCode,
		response.StatusDescription));
	//parse response
	DataContractJsonSerializer jsonSerializer = new DataContractJsonSerializer(typeof(PA2Response));
	object objResponse = jsonSerializer.ReadObject(response.GetResponseStream());
	result = objResponse as PA2Response;
//processing result
if (result.error == null)
{
	//process result
}
else
{
	//process error
}


Phone Append 2 Java Rest Code Snippet
PA2Response.PhoneInfo result = null;
PA2Response.Error error = null;
 
PA2RestClient PA2Client = new PA2RestClient();
PA2Response result = PA2Client.CompositePhoneAppend(name, addr, city, state, postalCode, isBusiness, licenseKey);
 
if (result != null) {
	error = result.Error;
	info = result.Phoneinfo;
}
 
//Process Results
if (error == null) {
	//DOTS Address Phone Append Results
		
}
 
//Process Errors
else{
}
	//DOTS Phone Append Error 
	
}


Phone Append 2 PHP Rest Code Snippets
$URL = "https://trial.serviceobjects.com/PA2/api.svc/CompositePhoneInfo/".rawurlencode($State)."/".rawurlencode($City)."/".rawurlencode($PostalCode)."/".rawurlencode($Address)."/".rawurlencode($Name)."/".rawurlencode($isBusiness)."/".rawurlencode($LicenseKey)."?format=json";	
// Get cURL resource
$curl = curl_init();
curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $URL, CURLOPT_USERAGENT => 'Service Objects Phone Append 2'));
curl_setopt($curl, CURLOPT_TIMEOUT, 5); //timeout in seconds
// Send the request & save response to $resp
$resp = curl_exec($curl);
$jsonIterator = new RecursiveIteratorIterator(new RecursiveArrayIterator(json_decode($resp, TRUE)), RecursiveIteratorIterator::SELF_FIRST);
foreach ($jsonIterator as $key => $val) 
{
	if(is_array($val)) 
	{
		echo "Phone Append 2 Results";
	} 
	else 
	{ 
		echo "$key";
		echo "$val";
	}
}


Phone Append 2 RoR Rest Code Snippets
      #This sets the default timeout for HTTParty get operation. This must be set in order to use the gem
      default_timeout = 10

      name = @request.name
      address = @request.address
      city = @request.city
      state = @request.state
      postalcode = @request.postalcode
      isbusiness = @request.isbusiness
      licensekey = @request.licensekey

     #Set Primary and Backup URLs as needed
      primaryURL = URI.encode("https://trial.serviceobjects.com/PA2/api.svc/CompositePhoneAppend?Name="+name+"&Address="+address+"&City="+city+"&State="+state+"&PostalCode="+postalcode+"&isBusiness="+isbusiness+"&LicenseKey="+licensekey)
      backupURL =  URI.encode("https://trial.serviceobjects.com/PA2/api.svc/CompositePhoneAppend?State="+ state+"&City="+city+"&PostalCode="+postalcode+"&Address="+address+"&Name="+name+"&isBusiness="+isbusiness+"&LicenseKey="+licensekey)
     
	 #These are set to access the hash that is returned
      @phoneresponse = "PhoneInfoResponse"
      @phoneinfo = "PhoneInfo"
      @error = "Error"
      #Begins the call the RESTful web service
      begin
        response = HTTParty.get(primaryURL, timeout: default_timeout)
        #processes the response to display to the screen
        
        #Passes the response from HTTParty and the hash key values to this method
        processresults(response)
       rescue StandardError => e
       		begin
       		#uses the backupURl in the event that the service encountered an error
       		response = HTTParty.get(backupURL, timeout: default_timeout)
          
          #processes the response returned from using the backupURL
           processresults(response)
          #If the backup url railed this will raise an error and display the 
          #error message returned from the HTTParty gem.
       		rescue StandardError => error
       		end
      end
  end
	private 
    def processresults(response)  
      #Processes Error Response from rest Client    
      #Processes Valid response from rest client  
     end


Phone Append 2 Python Rest Code Snippet
        mFullName =  FullName.get()
    if mFullName is None or  mFullName == "":
        mFullName = " "
    mFirstName =  FirstName.get()
    if mFirstName is None or  mFirstName == "":
        mFirstName = " "
    mLastName =  LastName.get()
    if mLastName is None or  mLastName == "":
        mLastName = " "
    mAddress =  Address.get()
    if mAddress is None or  mAddress == "":
        mAddress = " "
    mCity = City.get()
    if mCity is None or mCity == "":
        mCity = " "
    mState = State.get()
    if mState is None or mState == "":
        mState = " "
    mPostalCode = PostalCode.get()
    if mPostalCode is None or mPostalCode == "":
        mPostalCode = " "
    mLicenseKey = LicenseKey.get()
    if mLicenseKey is None or mLicenseKey == "":
        mLicenseKey = " "

    primaryURL = 'http://trial.serviceobjects.com/P2/api.svc/PhoneAppend?'
    backupURL = 'http://trial.serviceobjects.com/PA2/api.svc/PhoneAppend?'

    #The Requests package allows the user to format the path parameters like so instead of having to manually insert them into the URL
    inputs = {'FullName': mFullName, 'FirstName': mFirstName, 'LastName':mLastName, 'Address': mAddress, 'City': mCity, 'State': mState, 'PostalCode': mPostalCode, 'LicenseKey': mLicenseKey}
    try:
        result = requests.get(primaryURL, params=inputs)
        #Parses the XML response from the service into a python dictionary type
        outputs = xmltodict.parse(result.content)
        #Handel response and check for errors
    #Attempts to use the backupURL if the call to the primary URL failed
    except:
        try:
            result = requests.get(backupURL, params=inputs)
            #Parses the XML response from the service into a python dictionary type
            outputs = xmltodict.parse(result.content)
            #Handel response and check for errors
        #Displays an error message if the backup url failed.
        except:
            Label(swin.window, text='Error').pack()
            print (result)


Phone Append2 ColdFusion Code Snippet
<!--Makes Request to web service --->
<cfscript>
	try
	{
		if (isDefined("form.Action") AND Action neq "")
		{
			wsresponse = CreateObject("webservice", "http://trial.serviceobjects.com/pa2/api.svc?WSDL");							  
			outputs = wsresponse.phoneAppend("#FullName#", "#FirstName#", "#LastName#", "#Address#", "#City#", "#State#", "#PostalCode#" ,"#LicenseKey#");
			writedump(outputs.getPhoneInfo());
		}
	}
	catch(any Exception)
	{
		try
			{
				if (isDefined("form.Action") AND Action neq "")
				{
					wsresponse = CreateObject("webservice", "http://trial.serviceobjects.com/pa2/api.svc?WSDL");							  
					outputs = wsresponse.phoneAppend("#FullName#", "#FirstName#", "#LastName#", "#Address#", "#City#", "#State#", "#PostalCode#" ,"#LicenseKey#");
				}
			}
			catch(any Exception)	
				{
		  		 writeoutput("An Error Has Occured. Please Reload and try again #Exception.message#");		  		 
		 		}
	 }
</cfscript>


Phone Append 2 VB Rest Snippet
'encodes the URLs for the get Call. Set the primary and back urls as necessary
Dim primaryurl As String = "http://trial.serviceobjects.com/PA2/api.svc/PhoneAppend?State=" & state + "&City=" + city + "&PostalCode=" + postalcode + "&Address=" + address + "&FullName=" + fullname + "&LastName=" + lastname + "&FirstName=" + firstname + "&LicenseKey=" & licensekey
Dim backupurl As String = "http://trial.serviceobjects.com/PA2/api.svc/PhoneAppend?State=" & state + "&City=" + city + "&PostalCode=" + postalcode + "&Address=" + address + "&FullName=" + fullname + "&LastName=" + lastname + "&FirstName=" + firstname + "&LicenseKey=" & licensekey
Dim wsresponse As PA2Response.PhoneInfoResponse = httpGet(primaryurl)
'checks if a response was returned from the service, uses the backup url if response is null or a fatal error occured.
If wsresponse Is Nothing OrElse (wsresponse.[Error] IsNot Nothing AndAlso wsresponse.[Error].TypeCode = "3") Then
    wsresponse = httpGet(backupurl)
End If
If wsresponse.[Error].Type IsNot Nothing Then
    ProcessErrorResponse(wsresponse.[Error])
Else
    ProcessSuccessfulResponse(wsresponse)

End If


Phone Append 2 TSQL Rest Code Snippet
BEGIN
	SET @sUrl = 'http://ws.serviceobjects.com/pa2/api.svc/PhoneAppend?FullName=' + @fullname + '&FirstName=' + @firstname + '&LastName=' + @lastname + '&Address=' + @address + '&City=' + @city + '&State=' + @state + '&PostalCode=' + @postalcode + '&LicenseKey=' + @key
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'Get', @sUrl, false
	EXEC sp_OAMethod @obj, 'send'
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		SET @sBackupUrl = 'http://wsbackup.serviceobjects.com/pa2/api.svc/PhoneAppend?FullName=' + @fullname + '&FirstName=' + @firstname + '&LastName=' + @lastname + '&Address=' + @address + '&City=' + @city + '&State=' + @state + '&PostalCode=' + @postalcode + '&LicenseKey=' + @key
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'Get', @sBackupUrl, false
		EXEC sp_OAMethod @obj, 'send'
		EXEC sp_OAGetProperty @obj, 'responseText', @response OUT
	END
END

You can find and download full sample code to our services in various languages (PHP, JAVA and C#) by clicking here. Below is a C# version.

If you are looking for a particular integration not listed in our documentation please contact us at support@serviceobjects.com.

C#
using System;
using System.Collections.Generic;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using DOTSPA2_Soap.com.serviceobjects.trial;
using System.Configuration;
using System.Data;
namespace DOTSPA2_Soap
{
    public partial class _Default : System.Web.UI.Page
    {
     
        static int WEB_SERVICE_REQUEST_TIMEOUT; //In milliseconds
              
        protected void Page_Load(object sender, EventArgs e)
        {
            ErrorLabel.Visible = false;
            ResultGrid.Visible = false;
            ErrorGrid.Visible = false;
            try
            {
                WEB_SERVICE_REQUEST_TIMEOUT = Convert.ToInt32(ConfigurationManager.AppSettings["WebServiceRequestTimeout"]);
            }
            catch (Exception ex)
            {
                ErrorLabel.Visible = true;
                ErrorLabel.Text = "Page load Error: " + ex.Message;
            }
        }
        // handle the click image button event
        private void Imagebutton1_Click(object sender, System.Web.UI.ImageClickEventArgs e)
        {
            try
            {
                PhoneInfoResponse response = validateAddress(inputName.Text, inputAddress.Text, inputCity.Text, inputState.Text, inputZip.Text, inputIsBusiness.Text, inputLicenseKey.Text);
                ProcessResponse(response);
            }
            catch (Exception ex)
            {
                ErrorLabel.Visible = true;
                ErrorLabel.Text = ex.Message;
            }
        }
        //Create soap clients and request response from service
        private PhoneInfoResponse validateAddress(string inputName, string inputAddress, string inputCity, string inputState, string inputZip, string inputIsBusiness, string inputLicenseKey)
        {
            PhoneAppend2Client PA2Client_Primary = null;
            PhoneAppend2Client PA2Client_Backup = null;
            PhoneInfoResponse response = null;
            
            try
            {
                PA2Client_Primary = new PhoneAppend2Client("DOTSPA2PRIMARY");
                PA2Client_Primary.InnerChannel.OperationTimeout = new TimeSpan(0, 0, 0, WEB_SERVICE_REQUEST_TIMEOUT);
                response = PA2Client_Primary.CompositePhoneAppend(inputName, inputAddress, inputCity, inputState, inputZip, inputIsBusiness, inputLicenseKey);
                //NULL ERROR || FATAL ERROR RETURNED -- TRY BACKUP 
                if (response == null || (response.Error != null && response.Error.TypeCode == "3"))
                {
                    throw new Exception();
                }
                return response;
            }
            catch (Exception)
            {
                try
                {  
                    PA2Client_Backup = new PhoneAppend2Client("DOTSPA2BACKUP");
                    PA2Client_Backup.InnerChannel.OperationTimeout = new TimeSpan(0, 0, 0, WEB_SERVICE_REQUEST_TIMEOUT);
                    return PA2Client_Backup.CompositePhoneAppend(inputName, inputAddress, inputCity, inputState, inputZip, inputIsBusiness, inputLicenseKey);
                }
                catch (System.Exception e)
                {
                    throw e;
                }
                finally
                {
                    if (PA2Client_Backup != null) { PA2Client_Backup.Close(); }
                }
            }
            finally
            {
                if (PA2Client_Primary != null) { PA2Client_Primary.Close(); }
            }
        }
        //Process the returned object
        private void ProcessResponse(PhoneInfoResponse response)
        {
            try
            {
                if (response.Error != null)
                {
                    ProcessError(response.Error);
                }
                else
                {
                    ProcessResult(response.PhoneInfo);
                }
            }
            catch (Exception ex)
            {
                throw ex;
            }
        }
        //Process and display the error values
        private void ProcessError(PA2Error error)
        {
            try
            {
                DataTable dtError = new DataTable();
                //A case statement is used here because it is often useful to do different
                //things depeneding on which general type of error occurs.
                //Handle the errors according to your production needs.
                switch (System.Convert.ToInt32(error.TypeCode))
                {
                    case 1:
                        //Authorization Error
                        break;
                    case 2:
                        //User Input Error
                        break;
                    case 4:
                        //Domain Specific Error
                        break;
                    default:
                        //default (error code 3) Service Objects Fatal Error Error
                        break;
                }
                dtError.Columns.Add(new DataColumn("Output", typeof(string)));
                dtError.Columns.Add(new DataColumn("Values", typeof(string)));
                dtError.Rows.Add("Type", error.Type);
                dtError.Rows.Add("TypeCode", error.TypeCode);
                dtError.Rows.Add("Desc", error.Desc);
                dtError.Rows.Add("DescCode", error.DescCode);
                //
                ResultGrid.Visible = false;
                ErrorGrid.Visible = true;
                ErrorGrid.DataSource = new DataView(dtError);
                ErrorGrid.DataBind();
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        //Process and display the result values
        private void ProcessResult(PhoneInfo result)
        {
            try
            {
                DataTable dtProvider = new DataTable();
                dtProvider.Columns.Add(new DataColumn("Output", typeof(string)));
                dtProvider.Columns.Add(new DataColumn("Values", typeof(string)));
                dtProvider.Rows.Add("Phone", result.Phone);
                dtProvider.Rows.Add("Name", result.Name);
                dtProvider.Rows.Add("Address", result.Address);
                dtProvider.Rows.Add("City", result.City);
                dtProvider.Rows.Add("State", result.State);
                dtProvider.Rows.Add("PostalCode", result.PostalCode);
                dtProvider.Rows.Add("IsResidential", result.IsResidential);
                dtProvider.Rows.Add("Certainty", result.Certainty);
                dtProvider.Rows.Add("LineType", result.LineType);
                dtProvider.Rows.Add("Debug", result.Debug);
                ResultGrid.Visible = true;
                ErrorGrid.Visible = false;
                ResultGrid.DataSource = new DataView(dtProvider);
                ResultGrid.DataBind();
               
            }
            catch (Exception e)
            {
                throw e;
            }
        }
    }
}


PhoneAppend Example Request and Response


URL Request: 
https://trial.serviceobjects.com/PA2/api.svc/PhoneInfo/CA/Santa Barbara/93101/100 W Ortega St./Mike Wilson/Wilson/Mike/yourDevKey?format=json


Json Response
{"PhoneInfo":{"Phone":"(805) 961-2034","Name":"Mike Wilson","Address":"100 W Ortega St.","City":"Santa Barbara","State":"CA","PostalCode":"93101-2312","IsResidential":"True","Certainty":"High","LineType":"Landline","Debug":null},"Error":null}


URL Request: 
https://trial.serviceobjects.com/PA2/api.svc/PhoneInfo/CA/Santa Barbara/93101/100 W Ortega St./Mike Wilson/Wilson/Mike/yourDevKey?format=xml


XML Response
<PhoneInfoResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<PhoneInfo>
<Phone>(805) 961-2034</Phone>
<Name>Mike Wilson</Name>
<Address>100 W Ortega St.</Address>
<City>Santa Barbara</City>
<State>CA</State>
<PostalCode>93101-2312</PostalCode>
<IsResidential>True</IsResidential>
<Certainty>High</Certainty>
<LineType>Landline</LineType>
<Debug i:nil="true"/>

</PhoneInfo>
<Error i:nil="true"/>
</PhoneInfoResponse>

BusinessPhoneAppend Example Request and Response


URL Request:
https://trial.serviceobjects.com/PA2/api.svc/BusinessPhoneInfo/CA/Santa%20Barbara/93101/27%20E%20Cota/Service%20Objects/yourDevKey?format=json


Json Response
{"PhoneInfo":{"Phone":"(805) 963-1700","Name":"Service Objects","Address":"133 E De La Guerra St","City":"Santa Barbara","State":"CA","PostalCode":"93101-2228","IsResidential":"False","Certainty":"Medium","LineType":"Landline","Debug":null},"Error":null}


URL Request:
https://trial.serviceobjects.com/PA2/api.svc/BusinessPhoneInfo/CA/Santa%20Barbara/93101/27%20E%20Cota/Service%20Objects/yourDevKey?format=xml


XML Response
<PhoneInfoResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<PhoneInfo>
<Phone>(805) 963-1700</Phone>
<Name>Service Objects</Name>
<Address>133 E De La Guerra St</Address>
<City>Santa Barbara</City>
<State>CA</State>
<PostalCode>93101-2228</PostalCode>
<IsResidential>False</IsResidential>
<Certainty>Medium</Certainty>
<LineType>Landline</LineType>
<Debug i:nil="true"/>
</PhoneInfo>

<Error i:nil="true"/>
</PhoneInfoResponse>

CompositePhoneAppend Example Request and Response


URL Request: 
https://trial.serviceobjects.com/PA2/api.svc/CompositePhoneInfo/CA/Santa%20Barbara/93101/27%20E%20Cota%20St/Service%20Objects/true/yourDevKey?format=json


Json Response
{"PhoneInfo":{"Phone":"(805) 963-1700","Name":"Service Objects","Address":"133 E De La Guerra St","City":"Santa Barbara","State":"CA","PostalCode":"93101-2228","IsResidential":"False","Certainty":"Medium","LineType":"Landline","Debug":null},"Error":null}


URL Request: 
https://trial.serviceobjects.com/PA2/api.svc/CompositePhoneInfo/CA/Santa%20Barbara/93101/27%20E%20Cota%20St/Service%20Objects/true/yourDevKey?format=xml


XML Response
<PhoneInfoResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<PhoneInfo>
<Phone>(805) 963-1700</Phone>
<Name>Service Objects</Name>
<Address>133 E De La Guerra St</Address>
<City>Santa Barbara</City>
<State>CA</State>
<PostalCode>93101-2228</PostalCode>
<IsResidential>False</IsResidential>
<Certainty>Medium</Certainty>
<LineType>Landline</LineType>
<Debug i:nil="true"/>
</PhoneInfo>
<Error i:nil="true"/>
</PhoneInfoResponse>

Request Types


DOTS Phone Append 2 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. 
REST – All of the input data is appended to the URL in a REST style format where data is ordered by <Operation>/<Parameter1>/<Parameter2>..etc 
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


REST is one of our newest request types which aims to support multiple endpoint access to our services. Making a REST call to our service provides the functionality to specify a response format such as XML or JSON. 

REST URI Template:

PhoneAppend:

/PhoneInfo/State/City/PostalCode/Address/FullName/LastName/LicenseKey?format={xml,json} 


BusinessPhoneAppend:

/BusinessPhoneInfo/State/City/PostalCode/Address/BusinessName/LicenseKey?format={xml,json} 


CompositePhoneAppend:

/CompositePhoneInfo/State/City/PostalCode/Address/Name/IsBusiness/LicenseKey?format={xml,json}


Any Missing Parameters should be passed with a space between each

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/pa2/api.svc?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.

List of Operations

PhoneAppend --Uses the provided Full Name, First Name, Last Name, Address, City, State, Postal Code, License Key to return a phone number that matches the input information. 
BusinessPhoneAppend --Uses the provided BusinessName, Address, City, State, Postal Code, License Key to return a landline phone number. 
CompositePhoneAppend --Uses the provided Name, Address, City, State, Postal Code, IsBusiness, LicenseKey to return a landline phone number.

Operation Definitions

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

PhoneAppend

Uses the provided FullName, FirstName, LastName, Address, City, State, Postal Code, License Key to return a landline phone number.

PhoneAppend - Inputs

Name

Type

Description

FullName

String

The Full Name of the contact to return the telephone number.
**Optional to use Full Name versus First Name, Last Name

FirstName

String

The First Name of the contact to return the telephone number.

LastName

String

The Last Name of the contact to return the telephone number.

Address

String

The Address of the contact to return the telephone number.

City

String

The City of the contact to return the telephone number.

State

String

The State of the contact to return the telephone number.

PostalCode

String

The Postal Code of the contact to return the telephone number.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/phone/phone-append


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

Name

Type

Description

Phone

String

The landline phone number matching the found contact.

Name

String

The Name of the person matching the found contact

Address

String

The Address of the person matching the found contact.

City

String

The City of the person matching the found contact.

State

String

The State of the person matching the found contact.

PostalCode

String

The Postal Code of the person matching the found contact.

IsResidential

String

A determination of the matching contact is a business number or not.

Certainty

String

A rating scale of the accuracy of the matching contact given the supplied inputs. Values can be "Low" "Medium" or "High"

LineTypeStringA determination of the phone carrier line type. Possible values are "Landline", "Wireless", "VOIP", or "Unknown".

Debug

String

An internal field used for testing our services.


BusinessPhoneAppend

BusinessPhoneAppend returns a phone number based on provided inputs. The minimum required inputs are BusinessName City State.

GetPhoneAppend - Inputs

Name

Type

Description

BusinessName

String

The Business Name of the contact to return the telephone number.

Address

String

The Address of the contact to return the telephone number.

City

String

The City of the contact to return the telephone number.

State

String

The State of the contact to return the telephone number.

Postal Code

String

The Postal Code of the contact to return the telephone number.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/phone/phone-append


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

Name

Type

Description

Phone

String

The landline phone number matching the found contact.

Name

String

The Name of the person matching the found contact.

Address

String

The Address of the person matching the found contact.

City

String

The City of the person matching the found contact.

State

String

The State of the person matching the found contact.

PostalCode

String

The Postal Code of the person matching the found contact.

IsResidential

String

A determination of the matching contact is a business number or not.

Certainty

String

A rating scale of the accuracy of the matching contact given the supplied inputs. Values can be "Low" "Medium" or "High"

LineTypeStringA determination of the phone carrier line type. Possible values are "Landline", "Wireless", "VOIP", or "Unknown".

Debug

String

An internal field used for testing our services.


CompositePhoneAppend

This operation is a composite of PhoneAppend and BusinessPhoneAppend. CompositePhoneAppend provides the convenience for developers to code to one operation and is able to append phone numbers for business and residential contacts A parameter "IsBusiness" allows the client to specify whether the contact is a business or not. If left blank, the service can make the determination on its own, however, this increases the response time from the request.

CompositePhoneAppend makes use of additional name parsing logic when the IsBusiness parameter is not provided a value of True or False. This additional logic adds an increase in response time due to name-based logic that is performed on the inputs provided. It is recommended to specify a value for the IsBusiness parameter when used in applications that are time sensitive.

CompositePhoneAppend - Inputs

Name

Type

Description

Name

String

The Name of the contact to return the telephone number.

Address

String

The Address of the contact to return the telephone number.

City

String

The City of the contact to return the telephone number.

State

String

The State of the contact to return the telephone number.

Postal Code

String

The Postal Code of the contact to return the telephone number.

IsBusiness

String

A determination of the type of contact to append a phone number to. Values to submit are either "True","False" or leave field blank to allow the service to make the determination on its own. We leave this up to the client to make the determination based on how they intend to use the service

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/phone/phone-append


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

Name

Type

Description

Phone

String

The landline phone number matching the found contact.

Name

String

The Name of the person matching the found contact

Address

String

The Address of the person matching the found contact.

City

String

The City of the person matching the found contact.

State

String

The State of the person matching the found contact

PostalCode

String

The Postal Code of the person matching the found contact.

IsResidential

String

A determination of the matching contact is a business number or not.

Certainty

String

A rating scale of the accuracy of the matching contact given the supplied inputs. Values can be "Low" "Medium" or "High"

LineTypeStringA determination of the phone carrier line type. Possible values are "Landline", "Wireless", "VOIP", or "Unknown".

Debug

String

An internal field used for testing our services


Errors

Generally, an error is anything that happens during a run of DOTS Phone Append 2 that causes the service to fail. If an error occurs, an XML error message, similar to the one below, will result instead of the PhoneInfoResult output described above: 

Example:


*Error!*

  <Type>Authorization</Type>
  <TypeCode>1</TypeCode>
  <Desc>Your license key does not work on this service.</Desc>
  <DescCode>8</DescCode>


There are four error types described below.

Error Types

Type

TypeCode

Billable

Standard Across All Gen2 Web Services

Authorization

1

No

Yes

User Input

2

Yes

No

Service Objects Fatal

3

No

Yes

Domain Specific

4

Yes

No

Error type 1: Authorization

These are standard to all Generation 2 DOTS Web Services.

Desc CodeDescription
0Please provide a valid license key for this web service.
1The daily allowable number of transactions for this license key has been exceeded.
2The monthly allowable number of transactions for this license key has been exceeded.
3The total allowable number of transactions for this license key has been exceeded.
4There are not enough transactions available. Check your daily/monthly transaction limits.
5This license key has expired.
6This license key has not yet been activated.
7This operation is limited to specific usage. Please contact customer service to have your key enabled.
8Your license key does not work on this service.

Error type 2: User Input

User Input errors are caused when a user inputs an invalid value or fails to provide a certain input field altogether. If a developer creates a request and mistypes a parameter name, it will probably cause a User Input Error.

Desc CodeDescription
1Please enter a LicenseKey.
2Please enter a City/State or PostalCode.
3Please provide a name.

Error type 3: Service Objects Fatal

The Desc will always be the same and the DescCode has no meaning. This is standard to all Generation 2 DOTS Web Services. This is a rare error that signals either an application fault in the DOTS Phone Append 2 service or a Network/Connectivity issue.

DescCode

Description

1

Unhandled error. Please contact Service Objects.

Error type 4: Domain Specific

Domain specific errors represent the common errors seen in Service Objects services. Domain Specific errors indicate that the service completed successfully but the result is not good.

DescCode

Description

1

No phone number found for the given criteria.

2

Bad address information. Required fields: City/state or Postal Code are missing.
3Operation not supported.


FAQ

The Sample Code is Giving Strange Errors or is Crashing!

Most likely, the sample code cannot connect to Service Objects. 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/pa2/api.svc

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.

Phone Append 2 doesn't find any data for my information!

If your phone number is unlisted, by law, it cannot be found by searching by contact information. Additionally, if your number is for a cellular phone, Phone Append 2 cannot find your information.

Phone Append 2 did not return an address with the phone number!

Some addresses are not entered correctly and not all providers standardize their data, so the service will attempt to correct any mistakes and standardize the addresses before returning a result. In some rare cases, however, the addresses cannot be corrected to meet USPS standards. Instead of returning a bad address the service will instead return the phone with the data it has available and omits the portions of the address that could not be corrected.

Phone Append 2 is giving someone else's phone number for my information!

Phone Append 2's data is updated constantly. In the case that you just changed your number, it probably just has not been updated since you made the change. Sometimes phone companies take their time in publishing updates. If the information is not accurate, and the given phone number has not recently changed ownership, please let us know at support@serviceobjects.com.

Can Phone Append 2 give me the information for a disconnected number?

No, although we are working on procuring this information. If you are interested in using this data, please contact us at support@serviceobjects.com, and we will let you know when that has been implemented.

Can Phone Append 2 give me the information for a cell phone or wireless number?

No. This information was somewhat restricted until recently, and even those databases that are currently available do not cover every wireless number in the US. We are also in the process of procuring this information and will keep you updated if you are interested.

Can Phone Append 2 give me the information for a Canadian phone number?

Yes – sometimes. Our data set for Canada isn't as extensive as our dataset for the US, but Phone Append 2 returns information for Canadian phone numbers.

I'm Not a Programmer. How Do I Use DOTS Phone Append 2?

Service Objects runs batches for you! A free batch trial is available at
https://www.serviceobjects.com/batch/upload

Conclusion

Service Objects is pleased to offer you a free trial of DOTS Phone Append 2.

Technical questions or concerns can be directed to support@serviceobjects.com.

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


  
We want to hear from you! We're always looking to improve our developer guides. 
Please email your suggestions to devguidefeedback@serviceobjects.com.

  • No labels