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

Introduction


DOTS Lead Enhancement (also referred to as LE) is a publicly available XML web service that is designed to enhance, embellish and append additional elements to good leads. This service enhances the contact information with an emphasis on appending. 
This composite service takes as completely optional inputs: Name, email, phone number, address1, address2, city, region, country, and IP address. The idea for this service is "do what you can with the data you are given". This service makes use of many "ala carte" services provided by Service Objects, Inc to validate and append as best possible. This service works for both US and Canadian leads. Address and phone information is only available for US and Canada so other international leads will not work correctly. International names, emails and IPs are acceptable. 

The following services are used by DOTS Lead Enhancement:

  1. DOTS Address Validation – US and DOTS Address Validation – Canada to return validated and standardized addresses with basic address data (DPV, RDI, County etc.)
  2. DOTS Name Validation for basic name validation (e.g.( is the name valid, does it match any celebrity names, is it vulgar, or is it made up of random characters).
  3. DOTS Phone Exchange Geophone for reverse phone number lookups. This includes provider data (line type, carrier, and exchange information) .and contact data (name, address and phone type of the numbers owner).
  4. DOTS Email Validation2 for basic email checking (syntax, valid mail server and bogus/vulgar email detection etc...)
  5. DOTS IP Validation for basic IP address information (city, region, country and proxy information).
  6. DOTS Phone Append for returning alternative phone number information (a different phone number returned given a name and address).

Note: Currently this service has only one operation and the focus of that operation is to enhance residential leads. Business leads are not supported. A new operation geared toward business leads may be added in the future.

Integration


Integrating LE into your application should be easy and straightforward. If you are using a common platform, Service Objects may already have sample code built that you can use: 
https://www.serviceobjects.com/developers/sample-code/lead-enhancement

However, if you are using a common platform that does not already have sample code, you can ask Service Objects to build you an example. Email support@serviceobjects.com for more details.

Web Service Structure:

Web services are methods that integrate with other applications via the web, and encapsulate tricky business logic. Web services are too large of a topic to cover in this document, but Service Objects has developed its web services to be as easy to integrate and as accessible as possible. 
DOTS Lead Enhancement is a public XML web service that supports SOAP, POST, and GET operations.

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

The location of the WSDL, or Web Service Definition Language document, is here (This is also accessible via the "Service Definition" link.):
https://trial.serviceobjects.com/le/LeadEnhancement.asmx?WSDL

Important Note!
SOAP is done via POST, only with special XML markup in the post-body.

This WSDL is the definition of the 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. Whenever your utilities or IDE asks for a WSDL path to DOTS Lead Enhancement, you can provide this one. Every web service has operations that it offers to subscribers – methods that do different work and return different output. Currently DOTS Lead Enhancement has only one operation.

Code Snippets




Lead Enhancement C# Code Snippet
//Add a service to your application https://trial.serviceobjects.com/le/LeadEnhancement.asmx
LEClient_Primary = new LELibraryClient("DOTSLE");
response = LEClient_Primary.EnhanceResidentialLead(Name, Email, PhoneNumber, Address1, Address2, City, Region, PostalCode, Country, IPAddress, licenseKey);
		
if (response.Error != null)
{
	//Process Error
}
else
{
	//Process Response		
}


Lead Enhancement Java Code Snippet
ResidentialLeadResponse resp = null;
ResidentialLeadInfo result = null;
Error error = null;
// Create soap request
LVLibraryLocator locator = new LVLibraryLocator();
// use ssl
locator.setDOTSLeadEnhancementEndpointAddress("https://trial.serviceobjects.com/le/LeadEnhancement.asmx");
ILVLibrary lv = locator.getDOTSLeadEnhancement();
DOTSLeadEnhancementStub soap = (DOTSLeadEnhancementStub)lv;
soap.setTimeout(5000);// set timeout
resp = soap.enhanceResidentialLead(Name, Email, PhoneNumber, Address1, Address2, City, Region, PostalCode, Country, IPAddress, licenseKey);
result = resp.getResidentialLeadInfo();
error = resp.getError();
if(resp == null || (error != null && error.getTypeCode() == "3"))
{
	throw new Exception();
}
 
//Process Results
if(error == null){
	//DOTS Lead Enhancement Results	
}
//Process Errors
else{
	//DOTS Lead Enhancement Error Results	
}


Lead Enhancement PHP Code Snippets
<?php
// Set these values per web service <as needed>
$wsdlUrl = "https://trial.serviceobjects.com/le/LeadEnhancement.asmx?WSDL";

$params['Name'] = $Name;
$params['Email'] = $Email;
$params['PhoneNumber'] = $PhoneNumber;
$params['Address1'] = $Address1;
$params['Address2'] = $Address2;
$params['City'] = $City;
$params['Region'] = $Region;
$params['PostalCode'] = $PostalCode;
$params['Country'] = $Country;
$params['IPAddress'] = $IPAddress;
$params['LicenseKey'] = $LicenseKey;

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


Lead Enhancement RoR Code Snippets
		#Formats inputs into a hash to pass to Soap Client
		#Hash Keys must be named as they are shown here.
		message = 	{
					"Name" => @request.name,
					"Email" => @request.email,
					"PhoneNumber" => @request.phonenumber,
					"Address1" => @request.address1,
					"Address2" => @request.address2,
					"City" => @request.city,
					"Region" => @request.region,
					"PostalCode" => @request.postalcode,
					"Country" => @request.country,
					"IPAddress" => @request.ipaddress,
					"LicenseKey" => @request.licensekey,
					}

		#Implemented to make the code more readable when accessing the hash			
		@leresponse = :enhance_residential_lead_response
		@leresult = :enhance_residential_lead_result
		@leerror = :error

		#Set Primary and Backup URLs here as needed
		dotsLEPrimary = "https://trial.serviceobjects.com/le/LeadEnhancement.asmx?WSDL"
		dotsLEBackup = "https://trial.serviceobjects.com/le/LeadEnhancement.asmx?WSDL"

		begin
			#initializes the soap client. The convert request keys global is necessary to receive a response from the service.
			client = Savon.client(wsdl: dotsLEPrimary )
			#Calls the operation with given inptus and converts response to a hash.
			response = client.call(:enhance_residential_lead, 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: dotsLEBackup)
			#Sets the response to the backclient call to the operation and converts response to a hash.
			response = backupclient.call(:enhance_residential_lead, message: message).to_hash
			processresults(response)

			#If backup url failed, this will display the error received from the server
			rescue Savon::Error =>error
				@status = error
				@displaydata = {"error" => "A Big Error Occured"}
			end
		end
	end
	private 
	def processresults(response)	
			#Processes Error Response from soap Client		
			#Processes Valid response from soap client
	end


Lead Enhancement Python Code Snippets
    mName =  Name.get()
    if mName is None or  mName == "":
        mName = " "
    mEmail =  Email.get()
    if mEmail is None or  mEmail == "":
        mEmail = " "
    mPhoneNumber =  PhoneNumber.get()
    if mPhoneNumber is None or  mPhoneNumber == "":
        mPhoneNumber = " "
    mAddress1 =  Address1.get()
    if mAddress1 is None or  mAddress1 == "":
        mAddress1 = " "
    mAddress2 =  Address2.get()
    if mAddress2 is None or  mAddress2 == "":
        mAddress2 = " "
    mCity = City.get()
    if mCity is None or mCity == "":
        mCity = " "
    mRegion = Region.get()
    if mRegion is None or mRegion == "":
        mRegion = " "
    mPostalCode = PostalCode.get()
    if mPostalCode is None or mPostalCode == "":
        mPostalCode = " "
    mCountry = Country.get()
    if mCountry is None or mCountry == "":
        mCountry = " "
    mIPAddress = IPAddress.get()
    if mIPAddress is None or mIPAddress == "":
        mIPAddress = " "
    mLicenseKey = LicenseKey.get()
    if mLicenseKey is None or mLicenseKey == "":
        mLicenseKey = " "
    #Set the primary and backup URLs as needed
    primaryURL = 'https://trial.serviceobjects.com/le/LeadEnhancement.asmx?WSDL'
    backupURL = 'https://trial.serviceobjects.com/le/LeadEnhancement.asmx?WSDL'
    #This block of code calls the web service and prints the resulting values to the screen
    try:
        client = Client(primaryURL)
        result = client.service.EnhanceResidentialLead(Name=mName, Email=mEmail, PhoneNumber=mPhoneNumber, Address1=mAddress1, Address2=mAddress2, City=mCity, Region=mRegion, PostalCode=mPostalCode, Country=mCountry, IPAddress=mIPAddress, 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.EnhanceResidentialLead(Name=mName, Email=mEmail, PhoneNumber=mPhoneNumber, Address1=mAddress1, Address2=mAddress2, City=mCity, Region=mRegion, PostalCode=mPostalCode, Country=mCountry, IPAddress=mIPAddress, 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)


Lead Enhancement ColdFusion Code Snippet
<!--Makes Request to web service --->
<cfscript>
		try
		{
			if (isDefined("form.Action") AND Action neq "")
			{
				wsresponse = CreateObject("webservice", "https://trial.serviceobjects.com/le/LeadEnhancement.asmx?WSDL");							  
				outputs = wsresponse.enhanceResidentialLead("#Name#", "#Email#", "#PhoneNumber#", "#Address#", "#Address2#", "#City#", "#Region#", "#PostalCode#", "#Country#", "#IPAddress#", "#LicenseKey#");
			}
		}
	catch(any Exception){
		try
			{
				if (isDefined("form.Action") AND Action neq "")
				{
					wsresponse = CreateObject("webservice", "https://trial.serviceobjects.com/le/LeadEnhancement.asmx?WSDL");							  
					outputs = wsresponse.enhanceResidentialLead("#Name#", "#Email#", "#PhoneNumber#", "#Address#", "#Address2#", "#City#", "#Region#", "#State#", "#PostalCode#", "#Country#", "#IPAddress#", "#LicenseKey#");
				}
			}
			catch(any Exception)	
				{
		  		 writeoutput("An Error Has Occured. Please Reload and try again #Exception.message#");		  		 
		 		}
	    }
</cfscript>


Lead Enhancement VB Code Snippet
Try
    Dim ws As New LE.DOTSLeadEnhancementSoapClient
    Dim response As LE.Lead
    response = ws.EnhanceResidentialLead(Name.Text, Email.Text, PhoneNumber.Text, Address1.Text, Address2.Text, City.Text, Region.Text, PostalCode.Text, Country.Text, IPAddress.Text, LicenseKey.Text)
    If (response.Error Is Nothing) Then
        ProcessValidResponse(response)
    Else
        ProcessErrorResponse(response.Error)
    End If

Catch er As Exception
    Try
        ''Set Primary and Backup service references as necessary
        Dim wsbackup As New LE.DOTSLeadEnhancementSoapClient
        Dim response As LE.Lead
        response = wsbackup.EnhanceResidentialLead(Name.Text, Email.Text, PhoneNumber.Text, Address1.Text, Address2.Text, City.Text, Region.Text, PostalCode.Text, Country.Text, IPAddress.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


Lead Enhancement Apex Code Snippet
wwwServiceobjectsCom.Lead result;
try{
wwwServiceobjectsCom.DOTSLeadEnhancementSoap client = new wwwServiceobjectsCom.DOTSLeadEnhancementSoap();
result = client.EnhanceResidentialLead([Name], [Email], [PhoneNumber], [Address1], [Address2], [City], [Region], [PostalCode], [Country], [IPAddress], [LicenseKey]);
}
catch(Exception ex){
 //If the first request failed try the failover endpoint
wwwServiceobjectsCom.DOTSLeadEnhancementSoap backupClient = new wwwServiceobjectsCom.DOTSLeadEnhancementSoap();
//The backup environment will be provided to you upon purchasing a production license key
backupClient.endpoint_x = 'https://trial.serviceobjects.com/LE/api.svc/soap';
result = backupClient.EnhanceResidentialLead([Name], [Email], [PhoneNumber], [Address1], [Address2], [City], [Region], [PostalCode], [Country], [IPAddress], [LicenseKey]);
}


Lead Enhancement TSQL Code Snippet
SET @requestBody = '<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">'+
				   '<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">'+
				   '<EnhanceResidentialLead xmlns="http://www.serviceobjects.com/">'+
				   '<Name>' + @name + '</Name>'+
				   '<Email>' + @email + '</Email>'+
				   '<PhoneNumber>' + @phonenumber + '</PhoneNumber>'+
				   '<Address1>' + @address1 + '</Address1>'+
				   '<Address2>' + @address2 + '</Address2>'+
				   '<City>' + @city + '</City>'+
				   '<Region>' + @region + '</Region>'+
				   '<PostalCode>' + @postalcode + '</PostalCode>'+
				   '<Country>' + @country + '</Country>'+
				   '<IPAddress>' + @ipaddress + '</IPAddress>'+
				   '<LicenseKey>' + @key + '</LicenseKey>'+
				   '</EnhanceResidentialLead>'+
				   '</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', 'https://ws.serviceobjects.com/le/LeadEnhancement.asmx', 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', '"https://www.serviceobjects.com/EnhanceResidentialLead"'
	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', 'https://wsbackup.serviceobjects.com/le/LeadEnhancement.asmx', 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', '"https://www.serviceobjects.com/EnhanceResidentialLead"'
		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



Lead Enhancement C# Rest Code Snippet
//encodes the URLs for the get Call. Set the primary and back urls as necessary
string primaryurl = "https://trial.serviceobjects.com/le/LeadEnhancement.asmx/EnhanceResidentialLead?Name=" + WebUtility.UrlEncode(name) + "&Email=" + WebUtility.UrlEncode(email) + "&PhoneNumber=" + WebUtility.UrlEncode(phonenumber) + "&Address1=" + WebUtility.UrlEncode(address1) + "&Address2=" + WebUtility.UrlEncode(address2) + "&City=" + WebUtility.UrlEncode(city) + "&Region=" + WebUtility.UrlEncode(region) + "&PostalCode=" + WebUtility.UrlEncode(postalcode) + "&Country=" + WebUtility.UrlEncode(country) + "&IPAddress=" + WebUtility.UrlEncode(ipaddress) + "&LicenseKey=" + WebUtility.UrlEncode(licensekey);
string backupurl = "https://trial.serviceobjects.com/le/LeadEnhancement.asmx/EnhanceResidentialLead?Name=" + WebUtility.UrlEncode(name) + "&Email=" + WebUtility.UrlEncode(email) + "&PhoneNumber=" + WebUtility.UrlEncode(phonenumber) + "&Address1=" + WebUtility.UrlEncode(address1) + "&Address2=" + WebUtility.UrlEncode(address2) + "&City=" + WebUtility.UrlEncode(city) + "&Region=" + WebUtility.UrlEncode(region) + "&PostalCode=" + WebUtility.UrlEncode(postalcode) + "&Country=" + WebUtility.UrlEncode(country) + "&IPAddress=" + WebUtility.UrlEncode(ipaddress) + "&LicenseKey=" + WebUtility.UrlEncode(licensekey);
Lead wsresponse = 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 == null || (wsresponse.Error != null && wsresponse.Error.TypeCode == "3"));
{
    wsresponse = httpGet(backupurl);
}
if (wsresponse.Error != null)
{
    ProcessErrorResponse(wsresponse.Error);
}
else
{
    ProcessSuccessfulResponse(wsresponse);
}


Lead Enhancement Java Rest Code Snippet
JSONObject results = RestClient(mainURL);	
try {
	if (ErrorMessages != null || (results.getJSONObject("Lead").has("Error") && results.getJSONObject("Lead").getJSONObject("Error").get("Number") == "3")) {
		// BACKUP
		results = RestClient(backupURL);
	}
} catch (JSONException e) {
	// TODO Auto-generated catch block
	e.printStackTrace();
}

return results;


Lead Enhancement PHP Rest Code Snippet
$URL = "https://trial.serviceobjects.com/le/LeadEnhancement.asmx/EnhanceResidentialLead?Name=".urlencode($Name)."&Email=".urlencode($Email)."&PhoneNumber=".urlencode($PhoneNumber)."&Address1=".urlencode($Address1)."&Address2=".urlencode($Address2)."&City=".urlencode($City)."&Region=".urlencode($Region)."&PostalCode=".urlencode($PostalCode)."&Country=".urlencode($Country)."&IPAddress=".urlencode($IPAddress)."&LicenseKey=".urlencode($LicenseKey);
//use backup url once given purchased license key
$backupURL = "https://trial.serviceobjects.com/le/LeadEnhancement.asmx/EnhanceResidentialLead?Name=".urlencode($Name)."&Email=".urlencode($Email)."&PhoneNumber=".urlencode($PhoneNumber)."&Address1=".urlencode($Address1)."&Address2=".urlencode($Address2)."&City=".urlencode($City)."&Region=".urlencode($Region)."&PostalCode=".urlencode($PostalCode)."&Country=".urlencode($Country)."&IPAddress=".urlencode($IPAddress)."&LicenseKey=".urlencode($LicenseKey);
 
// Get cURL resource
$curl = curl_init();
curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $URL, CURLOPT_USERAGENT => 'DOTS Lead Enhancement'));
curl_setopt($curl, CURLOPT_TIMEOUT, 50); //timeout in seconds
// Send the request & save response to $resp
$resp = curl_exec($curl);
// Close request to clear up some resources
if($resp == false)
{
	echo "IN back up block";
	curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $backupURL, CURLOPT_USERAGENT => 'DOTS Lead Enhancement'));
	curl_setopt($curl, CURLOPT_TIMEOUT, 50); //timeout in seconds
	// Send the request & save response to $resp
	$resp = curl_exec($curl);
	if($resp == false)
	{
		echo "<b> Both rest calls failed </b>";
		curl_close($curl);
		return;
	}
}


Lead Enhancement RoR Rest Code Snippets
#Set Primary and Backup URLs as needed. This method encodes and standardizes the URI to pass to the REST service.
primaryURL = URI.encode("https://trial.serviceobjects.com/le/LeadEnhancement.asmx/EnhanceResidentialLead?Name="  + name.to_s + "&Email=" + email.to_s + "&PhoneNumber=" + phonenumber.to_s + "&Address1=" + address1.to_s + "&Address2=" + address2.to_s + "&City=" + city.to_s + "&Region=" + region.to_s + "&PostalCode=" + postalcode.to_s + "&Country=" + country.to_s + "&IPAddress=" + ipaddress.to_s + "&LicenseKey=" + licensekey.to_s)
backupURL = URI.encode("https://trial.serviceobjects.com/le/LeadEnhancement.asmx/EnhanceResidentialLead?Name="  + name.to_s + "&Email=" + email.to_s + "&PhoneNumber=" + phonenumber.to_s + "&Address1=" + address1.to_s + "&Address2=" + address2.to_s + "&City=" + city.to_s + "&Region=" + region.to_s + "&PostalCode=" + postalcode.to_s + "&Country=" + country.to_s + "&IPAddress=" + ipaddress.to_s + "&LicenseKey=" + licensekey.to_s)
#These are set to access the hash that is returned
@leresult ="Lead"
@leerror = "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 returned from HTTParty and processes them depending on the results
  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
 			@status = response
 			@displaydata = {"Error" => "A Big Error Occured"}
 		end
end


Lead Enhancement Python Rest Code Snippets
#The Requests package allows the user to format the path parameters like so instead of having to manually insert them into the URL
inputs = {'Name': mName, 'Email':mEmail, 'PhoneNumber':mPhoneNumber, 'Address1': mAddress1, 'Address2':mAddress2, 'City': mCity, 'Region': mRegion, 'PostalCode': mPostalCode, 'Country':mCountry, 'IPAddress':mIPAddress, '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)
    #checks the output for Errors and displays the info accordingly
    if 'Error' in outputs['Lead']:
        #loops through the response from the service and prints the values to the screen.
        for key, value in outputs['Lead']['Error'].iteritems():
            Label(swin.window, text=str(key) + " : " + str(value)).pack()
    else:
        #Removes unnecessary entries that were parsed into the python dictionary from XML response of the service
        outputs['Lead'].pop("@xmlns:xsi", None)
        outputs['Lead'].pop("@xmlns:xsd", None)
        outputs['Lead'].pop("@xmlns", None)
        for key, value in outputs['Lead'].iteritems():
            Label(swin.window, text=str(key) + " : " + str(value)).pack()

#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)
        #checks the output for Errors and displays the info accordingly
        if 'Error' in outputs['Lead']:
            #loops through the response from the service and prints the values to the screen.
            for key, value in outputs['Lead']['Error'].iteritems():
                Label(swin.window, text=str(key) + " : " + str(value)).pack()
        else:
            #Removes unnecessary entries that were parsed into the python dictionary from XML response of service
            outputs['Lead'].pop("@xmlns:xsi", None)
            outputs['Lead'].pop("@xmlns:xsd", None)
            outputs['Lead'].pop("@xmlns", None)
            for key, value in outputs['Lead'].iteritems():
                Label(swin.window, text=str(key) + " : " + str(value)).pack()


Lead Enhancement ColdFusion Rest Code Snippet
<!--Makes Request to web service --->
<cfIf isDefined("form.Action") AND Action neq ""  >
	<cftry>
		<cfset primaryURL = "https://trial.serviceobjects.com/le/LeadEnhancement.asmx/EnhanceResidentialLead?Name=#Name#&Email=#Email#&PhoneNumber=#PhoneNumber#&Address1=#Address1#&Address2=#Address2#&City=#City#&Region=#Region#&PostalCode=#PostalCode#&Country=#Country#&IPAddress=#IPAddress#&LicenseKey=#LicenseKey#">
		<cfhttp url="#primaryURL#" method="get" result="response">
		<cfset outputs = XmlParse(response.FileContent)>
	<cfcatch >
		<cftry>
			<cfset backupURL = "https://trial.serviceobjects.com/le/LeadEnhancement.asmx/EnhanceResidentialLead?Name=#Name#&Email=#Email#&PhoneNumber=#PhoneNumber#&Address1=#Address1#&Address2=#Address2#&City=#City#&Region=#Region#&PostalCode=#PostalCode#&Country=#Country#&IPAddress=#IPAddress#&LicenseKey=#LicenseKey#">
			<cfhttp url="#backupURL#" method="get" result="response">
			<cfset outputs = XmlParse(response.FileContent)>				
			<cfcatch type="any" name="error">
				<cfoutput>
					The Following Error Occured: "#error.Message#"
				</cfoutput>
			</cfcatch>
		</cftry>
	</cfcatch>
	</cftry>
</cfif>


Lead Enhancement VB Rest Code Snippet
Try
    Dim ws As New LE.DOTSLeadEnhancementSoapClient
    Dim response As LE.Lead
    response = ws.EnhanceResidentialLead(Name.Text, Email.Text, PhoneNumber.Text, Address1.Text, Address2.Text, City.Text, Region.Text, PostalCode.Text, Country.Text, IPAddress.Text, LicenseKey.Text)
    If (response.Error Is Nothing) Then
        ProcessValidResponse(response)
    Else
        ProcessErrorResponse(response.Error)
    End If

Catch er As Exception
    Try
        ''Set Primary and Backup service references as necessary
        Dim wsbackup As New LE.DOTSLeadEnhancementSoapClient
        Dim response As LE.Lead
        response = wsbackup.EnhanceResidentialLead(Name.Text, Email.Text, PhoneNumber.Text, Address1.Text, Address2.Text, City.Text, Region.Text, PostalCode.Text, Country.Text, IPAddress.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


Lead Enhancement TSQL Rest Code Snippet
BEGIN
	SET @sUrl = 'https://ws.serviceobjects.com/le/LeadEnhancement.asmx/EnhanceResidentialLead?Name=' + @name + '&Email=' + @email + '&PhoneNumber=' + @phonenumber + '&Address1=' + @address1 + '&Address2=' + @address2 + '&City=' + @city + '&Region=' + @region + '&PostalCode=' + @postalcode + '&Country=' + @country + '&IPAddress=' + @ipaddress + '&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 = 'https://wsbackup.serviceobjects.com/le/LeadEnhancement.asmx/EnhanceResidentialLead?Name=' + @name + '&Email=' + @email + '&PhoneNumber=' + @phonenumber + '&Address1=' + @address1 + '&Address2=' + @address2 + '&City=' + @city + '&Region=' + @region + '&PostalCode=' + @postalcode + '&Country=' + @country + '&IPAddress=' + @ipaddress + '&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.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Runtime.Serialization.Json;
using System.Data;
using System.Net;
using System.Configuration;
namespace DOTSLeadEnhancement
{
    public partial class LE_rest : System.Web.UI.Page
    {
        #region STATICS
        static string WEB_SERVICE_PRIMARY_URL; //Included in email from Service Objects
        static string WEB_SERVICE_BACKUP_URL; //Included in email from Service Objects (LIVE customers only)
        static int WEB_SERVICE_REQUEST_TIMEOUT; //In milliseconds
        #endregion
        protected void Page_Load(object sender, EventArgs e)
        {
            try
            {
                ErrorLabel.Visible = false;
                ErrorGrid.Visible = false;
                ResultGrid.Visible = false;
                WEB_SERVICE_REQUEST_TIMEOUT = Convert.ToInt32(ConfigurationManager.AppSettings["WebServiceRequestTimeout"]);
                WEB_SERVICE_PRIMARY_URL = ConfigurationManager.AppSettings["LE_PRIMARY.LE"];
                if (string.IsNullOrWhiteSpace(WEB_SERVICE_PRIMARY_URL))
                    throw new System.Exception("Primary URL not set. Check your Web.config file.");
                WEB_SERVICE_BACKUP_URL = ConfigurationManager.AppSettings["LE_BACKUP.LE"];
                if (string.IsNullOrWhiteSpace(WEB_SERVICE_BACKUP_URL))
                    throw new System.Exception("Backup URL not set. Check your Web.config file.");
            }
            catch (Exception ex)
            {
                ErrorLabel.Visible = true;
                ErrorLabel.Text = "Page load Error: " + ex.Message;
            }
        }
        protected void btn_GO_Click(object sender, EventArgs e)
        {
            string licenseKey, name, email,phonenumber, address1, address2, city, region, country, ipaddress, postalcode;
            postalcode = inputZipCode.Text; name = inputName.Text; email = inputEmail.Text; phonenumber = inputPhoneNumber.Text; address1 = inputAddress1.Text;
            address2 = inputAddress2.Text; city = inputCity.Text; region = inputRegion.Text; country = inputCountry.Text; ipaddress = inputIPAddress.Text;
            licenseKey = inputLicenseKey.Text;
            try
            {
                //NOTE: A missing parameter is not allowed
               
                if (String.IsNullOrWhiteSpace(name))
                    name = " ";
                if (String.IsNullOrWhiteSpace(email))
                    email = " ";
                if (String.IsNullOrWhiteSpace(phonenumber))
                    phonenumber = " ";
                if (String.IsNullOrWhiteSpace(address1))
                    address1 = " ";
                if (String.IsNullOrWhiteSpace(address2))
                    address2 = " ";
                if (String.IsNullOrWhiteSpace(city))
                    city = " ";
                if (String.IsNullOrWhiteSpace(region))
                    region = " ";
                if (String.IsNullOrWhiteSpace(country))
                    country = " ";
                if (String.IsNullOrWhiteSpace(ipaddress))
                    ipaddress = " ";
                if (String.IsNullOrWhiteSpace(postalcode))
                    postalcode = " ";
                if (String.IsNullOrWhiteSpace(licenseKey))
                    licenseKey = "yourDevKey";
                LEResponse response = MakeRequest(name, email, phonenumber, address1, address2, city, region, postalcode, country, ipaddress, licenseKey);
                ProcessResponse(response);
            }
            catch (Exception ex)
            {
                ErrorLabel.Text = ex.Message;
                ErrorLabel.Visible = true;
            }
        }
        //Creates URL and requests response from service 
        private static LEResponse MakeRequest(string name, string email, string phonenumber, string address1, string address2, string city, string region,string postalcode, string country, string ipaddress, string licenseKey)
        {
            /* 
            * Due to RFC compliance, the use of URL Paths has character limitations.  
            * Certain characters are invalid and cause HTTP Errors; these characters  
            * include #, /, ?,\ as well as some high bit characters.  
            * 
            * If you suspect that this may be an issue for you then it is recommended to change your 
            * request from the URL path parameter format to the query string parameter format.  
            * Example:  
            *     FROM {data}/{data2}/{key}?format=json  
            *     TO parameter1={data1}&parameter2={data2}&licensekey={key} 
            * Another alternative is to use HTTP Post instead of HTTP Get. 
            */
            LEResponse result = null;
            string mainURL = WEB_SERVICE_PRIMARY_URL + name + "/" + email + "/" + phonenumber + "/" + address1 + "/" + address2 + "/" + city + "/" + region + "/" + postalcode + "/" + country + "/" + ipaddress + "/" + licenseKey + "?format=json";
            string backupURL = WEB_SERVICE_BACKUP_URL + name + "/" + email + "/" + phonenumber + "/" + address1 + "/" + address2 + "/" + city + "/" + region + "/" + postalcode + "/" + country + "/" + ipaddress + "/" + licenseKey + "?format=json";
            try
            {
                result = HttpGet(mainURL);
                //NULL ERROR || FATAL ERROR RETURNED -- TRY BACKUP 
                if (result == null || (result.Error != null && result.Error.TypeCode == "3"))
                {
                    return HttpGet(backupURL);
                }
                else
                {
                    return result;
                }
            }
            catch (Exception e)
            {   //ERROR IN MAIN URL - USING BACKUP
                return HttpGet(backupURL);
            }
        }
        //HTTP Get Method and parse into user-defined object
        private static LEResponse HttpGet(string requestUrl)
        {
            try
            {
                //NOTE: URL encoding occurs automatically when creating the web request
                HttpWebRequest request = WebRequest.Create(requestUrl) as HttpWebRequest;
                request.Timeout = WEB_SERVICE_REQUEST_TIMEOUT;//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(LEResponse));
                    object objResponse = jsonSerializer.ReadObject(response.GetResponseStream());
                    LEResponse jsonResponse = objResponse as LEResponse;
                    return jsonResponse;
                }
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        //Process the returned user-defined object
        private void ProcessResponse(LEResponse response)
        {
            try
            {
                //processing result
                if (response.Error == null)
                {
                    ProcessResult(response.ResidentialLeadInfo);
                }
                //processing error
                else
                {
                    ProcessError(response.Error);
                }
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        //Process and display the result values
        private void ProcessResult(Residential 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("NameIn", result.NameIn);
                dtProvider.Rows.Add("EmailAddressIn", result.EmailAddressIn);
                dtProvider.Rows.Add("PhoneNumberIn", result.PhoneNumberIn);
                dtProvider.Rows.Add("Address1In", result.Address1In);
                dtProvider.Rows.Add("Address2In", result.Address2In);
                dtProvider.Rows.Add("CityIn", result.CityIn);
                dtProvider.Rows.Add("RegionIn", result.RegionIn);
                dtProvider.Rows.Add("PostalCodeIn", result.PostalCodeIn);
                dtProvider.Rows.Add("CountryIn", result.CountryIn);
                dtProvider.Rows.Add("IPAddressIn", result.IPAddressIn);
                dtProvider.Rows.Add("FirstNameOut", result.FirstNameOut);
                dtProvider.Rows.Add("MiddleNameOut", result.MiddleNameOut);
                dtProvider.Rows.Add("LastNameOut", result.LastNameOut);
                dtProvider.Rows.Add("GenderOut", result.GenderOut);
                dtProvider.Rows.Add("FirstNameFound", result.FirstNameFound);
                dtProvider.Rows.Add("LastNameFound", result.LastNameFound);
                dtProvider.Rows.Add("NameNotesDesc", result.NameNotesDesc);
                dtProvider.Rows.Add("NameNotesCode", result.NameNotesCode);
                dtProvider.Rows.Add("Address1Out", result.Address1Out);
                dtProvider.Rows.Add("Address2Out", result.Address2Out);
                dtProvider.Rows.Add("CityOut", result.CityOut);
                dtProvider.Rows.Add("CountyOut", result.CountyOut);
                dtProvider.Rows.Add("RegionOut", result.RegionOut);
                dtProvider.Rows.Add("PostalCodeOut", result.PostalCodeOut);
                dtProvider.Rows.Add("CountryOut", result.CountryOut);
                dtProvider.Rows.Add("IsAddressDPV", result.IsAddressDPV);
                dtProvider.Rows.Add("IsAddressResidential", result.IsAddressResidential);
                dtProvider.Rows.Add("AddressNotesDesc", result.AddressNotesDesc);
                dtProvider.Rows.Add("AddressNotesCode", result.AddressNotesCode);
                dtProvider.Rows.Add("AddressErrorDesc", result.AddressErrorDesc);
                dtProvider.Rows.Add("AddressErrorCode", result.AddressErrorCode);
                dtProvider.Rows.Add("PhoneNumberOut", result.PhoneNumberOut);
                dtProvider.Rows.Add("CarrierName", result.CarrierName);
                dtProvider.Rows.Add("ExchangeCity", result.ExchangeCity);
                dtProvider.Rows.Add("ExchangeRegion", result.ExchangeRegion);
                dtProvider.Rows.Add("ExchangeCountry", result.ExchangeCountry);
                dtProvider.Rows.Add("PhoneLineType", result.PhoneLineType);
                dtProvider.Rows.Add("PhoneNumberErrorDesc", result.PhoneNumberErrorDesc);
                dtProvider.Rows.Add("PhoneNumberErrorCode", result.PhoneNumberErrorCode);
                dtProvider.Rows.Add("EmailAddressOut", result.EmailAddressOut);
                dtProvider.Rows.Add("IsEmailAddressFree", result.IsEmailAddressFree);
                dtProvider.Rows.Add("IsEmailAddressGood", result.IsEmailAddressGood);
                dtProvider.Rows.Add("EmailNotesDesc", result.EmailNotesDesc);
                dtProvider.Rows.Add("EmailNotesCode", result.EmailNotesCode);
                dtProvider.Rows.Add("EmailErrorDesc", result.EmailErrorDesc);
                dtProvider.Rows.Add("EmailErrorCode", result.EmailErrorCode);
                dtProvider.Rows.Add("IPAddressCity", result.IPAddressCity);
                dtProvider.Rows.Add("IPAddressRegion", result.IPAddressRegion);
                dtProvider.Rows.Add("IPAddressCountry", result.IPAddressCountry);
                dtProvider.Rows.Add("IPAddressCountryISO2", result.IPAddressCountryISO2);
                dtProvider.Rows.Add("IPAddressCountryIOS3", result.IPAddressCountryISO3);
                dtProvider.Rows.Add("IPAddressCertainty", result.IPAddressCertainty);
                dtProvider.Rows.Add("IPAddressISP", result.IPAddressISP);
                dtProvider.Rows.Add("IPAddressNetblockOwner", result.IPAddressNetblockOwner);
                dtProvider.Rows.Add("IPAddressIsProxy", result.IPAddressIsProxy);
                dtProvider.Rows.Add("IPAddressProxyType", result.IPAddressProxyType);
                dtProvider.Rows.Add("IPAddressErrorDesc", result.IPAddressErrorDesc);
                dtProvider.Rows.Add("IPAddressErrorCode", result.IPAddressErrorDesc);
                dtProvider.Rows.Add("DEBUG", result.DEBUG);
                ResultGrid.Visible = true;
                ErrorGrid.Visible = false;
                ResultGrid.DataSource = new DataView(dtProvider);
                ResultGrid.DataBind();
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        //Process and display the error values
        private void ProcessError(Error 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;
            }
        }
    }
}


       


EnhanceResidentialLead Example Request and Response

URL Request: 
https://trial.serviceobjects.com/le/LeadEnhancement.asmx/EnhanceResidentialLead?Name=Homer+Simpson&Email=test%40hotmail.com&PhoneNumber=8055551234&Address1=123+Fake+St&Address2=&City=Santa+Barbara&Region=CA&PostalCode=93101&Country=USA&IPAddress=127.0.0.1&LicenseKey=licenseKey


XML Response
<ResidentialLeadResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ResidentialLeadInfo>
<NameIn>Homer Simpson</NameIn>
<EmailAddressIn>test@hotmail.com</EmailAddressIn>
<PhoneNumberIn>8055551234</PhoneNumberIn>
<Address1In>123 Fake street</Address1In>
<Address2In></Address2In>
<CityIn>Santa Barbara</CityIn>
<RegionIn>CA</RegionIn>
<PostalCodeIn>93101</PostalCodeIn>
<CountryIn>usa</CountryIn>
<IPAddressIn>127.0.0.1</IPAddressIn>
<FirstNameOut>Homer</FirstNameOut>
<MiddleNameOut/>
<LastNameOut>Simpson</LastNameOut>
<GenderOut>MALE</GenderOut>
<FirstNameFound>TRUE</FirstNameFound>
<LastNameFound>TRUE</LastNameFound>
<NameNotesDesc>Name may be a well known character or celebrity.</NameNotesDesc>
<NameNotesCode>1</NameNotesCode>
<Address1Out/>
<Address2Out/>
<CityOut/>
<CountyOut/>
<RegionOut/>
<PostalCodeOut/>
<CountryOut/>
<IsAddressDPV/>
<AddressNotesDesc/>
<AddressNotesCode/>
<AddressErrorDesc>Street not found.</AddressErrorDesc>
<AddressErrorCode>1</AddressErrorCode>
<PhoneNumberOut>8055551234</PhoneNumberOut>
<CarrierName>PACIFIC BELL</CarrierName>
<ExchangeCity>BAKERSFIELD</ExchangeCity>
<ExchangeRegion>CALIFORNIA</ExchangeRegion>
<ExchangeCountry>USA</ExchangeCountry>
<PhoneLineType>LANDLINE</PhoneLineType>
<PhoneNumberErrorDesc>Phone Number is reserved.</PhoneNumberErrorDesc>
<PhoneNumberErrorCode>2</PhoneNumberErrorCode>
<EmailAddressOut>test@hotmail.com</EmailAddressOut>
<IsEmailAddressFree>UNKNOWN</IsEmailAddressFree>
<IsEmailAddressGood>FALSE</IsEmailAddressGood>
<EmailNotesDesc>Email mailbox is known to be invalid.</EmailNotesDesc>
<EmailNotesCode>7</EmailNotesCode>
<EmailErrorDesc/>
<EmailErrorCode/>
<IPAddressCity/>
<IPAddressRegion/>
<IPAddressCountry/>
<IPAddressCountryISO2/>
<IPAddressCountryISO3/>
<IPAddressCertainty/>
<IPAddressISP/>
<IPAddressNetblockOwner/>
<IPAddressIsProxy/>
<IPAddressProxyType/>
<IPAddressErrorDesc>IP Address was not found.</IPAddressErrorDesc>
<IPAddressErrorCode>1</IPAddressErrorCode>

</ResidentialLeadInfo>



</ResidentialLeadResponse>



Request Types

LE 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 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 in 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 all you have to do is 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 give your IDE (Integrated Development Environment) the URL to the WSDL of a web service (https://trial.serviceobjects.com/le/LeadEnhancement.asmx?WSDL) and it will 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.

XML Parsing

If you are not using an environment that creates 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 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 extra minutes to integrate 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 input 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

EnhanceResidentialLead (Recommended Operation) – Given any of the optional values: name, address, phone, email and IP attempt to validate, embellish and append as much data as possible to enhance the quality of the lead.

Operation Definitions

This document defines the input, output and behavior of the web service operations in DOTS Lead Enhancement.

EnhanceResidentialLead (Recommended Operation)

This is the main operation for validating and enhancing leads. It will attempt to append and enhance any lead given any combination of Name, Email, Phone Number, Address, Address2, City, Region, Postal Code, Country, and/or IP Address. This operation is designed for residential leads. Business addresses will be identified as such and business phone contacts will be returned if given a phone number for a business but it is expected that the leads themselves will be primarily residential information. The name testing will not work if given a company name. A business oriented operation will likely be planned for a future release. This operation will likely involve different data sources and tests not run during residential lead testing.

EnhanceResidentialLead Inputs

Name

Type

Description

Name

String

The name to validate.

Email

String

The email address to validate.

PhoneNumber

String

The phone number to validate.

Address1

String

The address to validate.

Address2

String

Extra address information to include for validation.

City

String

The city to validate.

Region

String

The region to validate.

PostalCode

String

The postal code to validate.

Country

String

The country to validate.

IPAddress

String

The IP address to validate.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/lead-validation-bundles/lead-enhancement


Important Note!
For any output fields, along with the states possible outputs in the "Values" column, expect that a blank result (empty string "") is also possible. It should never happen, but smart programming plans for potential NULL values for output fields as well.


EnhanceResidentialLead Outputs

Name

Type

Values

Description

NameIn

String

Varies

The original name.

EmailAddressIn

String

Varies

The original email.

PhoneNumberIn

String

Varies

The original number.

Address1In

String

Varies

The original address.

Address2In

String

Varies

The original address2.

CityIn

String

Varies

The original city.

RegionIn

String

Varies

The original region.

PostalCodeIn

String

Varies

The original postal code.

CountryIn

String

Varies

The original country.

IPAddressIn

String

Varies

The original IP.

FirstNameOut

String

Varies

The parsed out likely first name.

MiddleNameOut

String

Varies

The parsed out likely middle name

LastNameOut

String

Varies

The parsed out likely last name.

GenderOut

String

MALE,
PROBABLY MALE,
PROBABLY FEMALE, FEMALE, UNKNOWN

The likely gender of the lead.

FirstNameFound

String

TRUE, FALSE

The parsed out first name was identified as valid.

LastNameFound

String

TRUE, FALSE

The parsed out last name was identified as valid.

NameNotesDesc

String

See below

Extra informational notes about the name. See below for values.

NameNotesCode

String

Numerical code

A code associated with the name notes. See below for values.

Address1Out

String

Varies

The validated and standardized resulting address.

Address2Out

String

Varies

A placeholder for extra information that is not part of the standardized address.

CityOut

String

Varies

The validated and standardized city.

RegionOut

String

Varies

The validated and standardized region.

PostalCodeOut

String

Varies

The validated and standardized postal code.

CountryOut

String

Varies

The country the address is located in.

IsAddressDPV

String

TRUE, FALSE, UNKNOWN

An indicator telling if the standardized address is recognized as deliverable by the USPS.

IsAddressResidential

String

TRUE, FALSE

An indicator telling if the standardized address is recognized as residential by the USPS.

AddressNotesDesc

String

See below

Informational notes about the deliverability of the standardized address.

AddressNotesCode

String

Numerical code

A code associated with the address notes. See below for values.

AddressErrorDesc

String

See below

A description of any errors associated with the standardized address. See below for values.

AddressErrorCode

String

Numerical code

A code associated with the error description. See below for values.

PhoneNumberOut

String

Varies

A cleaned 10 digit phone number. Special characters and extension information removed.

CarrierName

String

Varies

The telephone company that owns the block of numbers designated by the first 7 digits of the number.

ExchangeCity

String

Varies

The city that the exchange (block of first 7 digits) belongs in.

ExchangeRegion

String

Varies

The region that the exchange (block of first 7 digits) belongs in.

ExchangeCountry

String

Varies3 character code

The three character country code that the exchange (block of first 7 digits) belongs in.

PhoneLineType

String

LANDLINE, WIRELESS, VOIP,
UNKNOWN

The line type of the given phone number.

PhoneNumberErrorDesc

String

See below

A description of any errors associated with the given phone number. See below for details.

PhoneNumberErrorCode

String

Numerical code

A numerical code associated with the error description. See below for values.

EmailAddressOut

String

Varies

A corrected and cleaned email address.

IsEmailAddressFree

String

TRUE, FALSE, UNKNOWN

An indicator of whether or not the email is available to anyone freely.

IsEmailAddressGood

String

TRUE, FALSE, UNKNOWN

An indicator of whether the email is known to be bad based on testing. See FAQ for more detail.

EmailNotesDesc

String

See below

Noteworthy information discovered about the email. See below for a complete list.

EmailNotesCode

String

Numerical code

A numerical code associated with the note above.

EmailErrorDesc

String

See below

A description of any errors associated with the email. See below for a complete list.

EmailErrorCode

String

Numerical code

A numerical code associated with the error above.

IPAddressCity

String

Varies

The city associated with the IP address.

IPAddressRegion

String

Varies

The state or province associated with the IP address.

IPAddressCountry

String

Varies

The country associated with the IP address.

IPAddressCountryISO2

String

2 character code

The two character country code associated with the IP address.

IPAddressCountryISO3

String

3 character
code

The three character country code associated with the IP address.

IPAddressCertainty

String

0-100

A certainty value for how accurate the IP address information is likely to be.

IPAddressISP

String

Varies

The ISP which assigned the IP address.

IPAddressNetblockOwner

String

Varies

The network owner to which the IP address is allocated.

IPAddressIsProxy

String

TRUE, FALSE, UNKNOWN

Indicates whether the IP address is a known proxy.

IPAddressProxyType

String

PRIVATE, PUBLIC, ANONYMOUS

Indicates the type of proxy found.

IPAddressErrorDesc

String

See below

A description of any errors associated with the IP address. See below for a complete list.

IPAddressErrorCode

String

Numerical code

A numerical code associated with the error above.


Error and Note Possible Values

Several of the DOTS Lead Enhancement output fields contain description and code results that have set values. The following section lists the code and description for all possible results. The headers contain the code and description name exactly as they appear in the output. See FAQ for more details on certain descriptions.

NameNotesCode

NameNotesDesc

1

Name may be a well-known character or celebrity.

2

Name may be vulgar.

3

Name may be nonsensical.

4

Name may be made of random characters.

5

Name may be a dictionary word.

Address Notes

AddressNotesCode

AddressNotesDesc

1

Yes, the input record is a valid mailing address.

2

No, the input record is not in the DPV database of valid mailing addresses.

3

The apartment or rural route box number is not valid, although the house number or rural route is valid.

4

The input record is a valid mailing address, but is missing the apartment or rural route box number.

Address Errors

AddressErrorsCode

AddressErrorsDesc

1

Street not found.

2

Street number or box number out of range.

3

Address not found.

4

Multiple addresses match.

5

Insufficient address data.

Phone Number Errors

PhoneNumberErrorCode

PhoneNumberErrorDesc

1

Phone Number is invalid.

2

Phone Number is reserved

Email Notes*

EmailNotesCode

EmailNotesDesc

1

Email belongs to a catchall server.

2

Email appears to be bogus.

3

Email contains vulgar words.

4

Email is established with spammers.

5

Email is an alias.

6

Email appears to contain random characters.

7

Email mailbox is known to be invalid.


Important Note!
Email Notes are the only output fields that allows for multiple results. So for example, EmailNotesDesc could read "*Email belongs to a catchall server. Email contains vulgar words." with the corresponding EmailNotesCode: "*1,3"


Email Errors

EmailErrorsCode

EmailErrorsDesc

1

Email has bad syntax.

2

Email domain or server is not valid.

IP Errors

IPErrorCode

IPErrorDesc

1

IP Address was not found.

2

IP Address does not appear to have valid syntax.

3

IP Address appears to belong to a private/local network.

Errors

Anything that happens during a run of DOTS Lead Enhancement that causes it to be unable to finish its normal processing is an error. If an error occurs, something like the following will be the result instead of the normal output: 
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. For DOTS Lead Enhancement, the first two will be the most common.

Error Types

Type

TypeCode

Billable

Standard for 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.

DescCode

Desc

0

Unknown authorization error.

1

Please provide a valid license key for this web service.

2

The daily allowable number of transactions for this license key has been exceeded.

3

The monthly allowable number of transactions for this license key has been exceeded.

4

The total allowable number of transactions for this license key has been exceeded.

5

There are not enough transactions available. Check your daily/monthly transaction limits.

6

This license key has not yet been activated.

7

This license key has expired.

8

Your license key does not work on this service.

Error type 2: User Input

These errors occur as a result of bad input. This is difficult as DOTS Lead Enhancement will accept whatever input is given to it and do the best it can. All inputs with the exception of License Key are optional.

There are currently no user input errors for this service.

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 a bug in the DOTS Lead Enhancement service, or a Network/Connectivity issue.

DescCode

Desc

1

Unhandled error. Please contact Service Objects.

Error type 4: Domain Specific

Domain specific errors represent the normal errors seen in Service Objects services. For example, if the user is looking for an address in DOTS Address Validation and the address does not exist, a valid domain specific error is "Address not found."

Example Leads

The following are two leads, one good and one bad, to illustrate what the service can do. The first lead is Mr. Bob Smith. He is not a real person and his data is not real, but the following results show what a good lead would look like. For the purpose of this example, all of the data inputs are good and all return maximum appended information. The first and last name are properly broken out and validated. The input street address is standardized and corrected by USPS standards and found to be delivery point valid (DPV). The phone number returns good exchange information and a contact matching the original input data. The emails domain and server are checked and returned as valid. Finally, the IP address is validated and returns a local ISP.

<Lead>
  <NameIn> Mr. Bob Smith Jr</NameIn>
  <EmailAddressIn>bsmith@aol.com</EmailAddressIn>
  <PhoneNumberIn>(805)/555/4043</PhoneNumberIn>
  <Address1In>802 E Cota Street</Address1In>
  <Address2In />
  <CityIn>Santa Barbara</CityIn>
  <RegionIn>CA</RegionIn>
  <PostalCodeIn>93101</PostalCodeIn>
  <CountryIn>USA</CountryIn>
  <IPAddressIn>64.138.19.68</IPAddressIn>
  <FirstNameOut>Bob</FirstNameOut>
  <MiddleNameOut />
  <LastNameOut>Smith</LastNameOut>
  <GenderOut>MALE</GenderOut>
  <FirstNameFound>TRUE</FirstNameFound>
  <LastNameFound>TRUE</LastNameFound>
  <NameNotesDesc />
  <NameNotesCode />
  <Address1Out>802 E Cota St</Address1Out>
  <Address2Out />
  <CityOut>Santa Barbara</CityOut>
  <CountyOut>Santa Barbara</CountyOut>
  <RegionOut>CA</RegionOut>
  <PostalCodeOut>93103</ PostalCodeOut>
  <CountryOut>USA</CountryOut>
  <IsAddressDPV>TRUE</IsAddressDPV>
  <IsAddressResidential>TRUE</IsAddressResidential>
  <AddressNotesDesc>Yes, the input record is a valid mailing address.</AddressNotesDesc>
  <AddressNotesCode>1</AddressNotesCode>
  <AddressErrorDesc />
  <AddressErrorCode />
  <PhoneNumberOut>8055554043</PhoneNumberOut>
  <CarrierName>SPRINT COMMUNICATIONS COMPANY, L.P. - CA</CarrierName>
  <ExchangeCity>SANTA BARBARA</ExchangeCity>
  <ExchangeRegion>CA</ExchangeRegion>
  <ExchangeCountry />
  <PhoneLineType>LANDLINE</PhoneLineType>
  <PhoneNumberErrorDesc />
  <PhoneNumberErrorCode />
  <EmailAddressOut>bsmith@aol.com</EmailAddressOut>
  <IsEmailAddressFree>UNKNOWN</IsEmailAddressFree>
  <IsEmailAddressGoodValid>TRUE</IsEmailAddressGoodValid>
  <EmailNotesDesc />
  <EmailNotesCode />
  <EmailErrorDesc />
  <EmailErrorCode />
  <IPAddressCity>Santa Barbara</IPAddressCity>
  <IPAddressRegion>CA</IPAddressRegion>
  <IPAddressCountry>United States</IPAddressCountry>
  <IPAddressCountryISO2>US</IPAddressCountryISO2>
  <IPAddressCountryISO3>USA</IPAddressCountryISO3>
  <IPAddressCertainty>95</IPAddressCertainty>
  <IPAddressISP>Masergy Communications</IPAddressISP>
  <IPAddressNetblockOwner>CARDINAL SOLUTIONS GROUP</IPAddressNetblockOwner>
  <IPAddressIsProxy>FALSE</IPAddressIsProxy>
  <IPAddressProxyType />
  <IPAddressErrorDesc />
  <IPAddressErrorCode />
 </Lead>


The next lead is an obvious fake, but it illustrates some of the results for bad information. Every element in this lead is fake and errors or other information is returned describing the issues found. This lead has been run through the DOTS Lead Enhancement service. The given name is validated and identified as good, but a note is added to mention that a match with a well know character has been made. The Address was made up and an error of "Street not found." is given in the output. Likewise, the phone number is also made up and is given an error of "Invalid number.". The email comes from a good domain and server, but notes threetwo issues with the email address: It's a catchall server, and it appears to be bogus, contains a vulgar word, and it has been found in spam lists. Finally, a true IP address has not been given, instead, an IP designating a local area network has.

<Lead>
  <NameIn>Homer Simpson</NameIn>
  <EmailAddressIn>testshit@hotmail.com</EmailAddressIn>
  <PhoneNumberIn>6666666666</PhoneNumberIn>
  <Address1In>123 fake street</Address1In>
  <Address2In />
  <CityIn>Santa Barbara</CityIn>
  <RegionIn>CO</RegionIn>
  <PostalCodeIn>93103</PostalCodeIn>
  <CountryIn>USA</CountryIn>
  <IPAddressIn>127.0.0.1</IPAddressIn>
  <FirstNameOut>Homer</FirstNameOut>
  <MiddleNameOut />
  <LastNameOut>Simpson</LastNameOut>
  <GenderOut>MALE</GenderOut>
  <FirstNameFound>TRUE</FirstNameFound>
  <LastNameFound>TRUE</LastNameFound>
  <NameNotesDesc>Name may be a well known character or celebrity.</NameNotesDesc>
  <NameNotesCode>1</NameNotesCode>
  <Address1Out />
  <Address2Out />
  <CityOut />
  <CountyOut />
  <RegionOut />
  <PostalCodeOut />
  <CountryOut />
  <IsAddressDPV />
 <IsAddressResidential />
  <AddressNotesDesc />
  <AddressNotesCode />
  <AddressErrorDesc>Street not found.</AddressErrorDesc>
  <AddressErrorCode>1</AddressErrorCode>
  <PhoneNumberOut>6666666666</PhoneNumberOut>
  <CarrierName />
  <ExchangeCity />
  <ExchangeRegion />
  <ExchangeCountry />
  <PhoneLineType>UNKNOWN</PhoneLineType>
  <PhoneNumberErrorDesc>Phone Number is invalid.</PhoneNumberErrorDesc>
  <PhoneNumberErrorCode>1</PhoneNumberErrorCode>
  <EmailAddressOut>shit@hotmail.com</EmailAddressOut>
  <IsEmailAddressFree>TRUE</IsEmailAddressFree>
  <IsEmailAddressGoodValid>FALSETRUE</IsEmailAddressGoodValid>
  <EmailNotesDesc>Email belongs to a catchall server. Email appears to be bogus. Email is established with spammers.Email belongs to a catchall server. Email contains vulgar words.</EmailNotesDesc>
  <EmailNotesCode>1,2,41,3</EmailNotesCode>
  <EmailErrorDesc />
  <EmailErrorCode />
  <IPAddressCity />
  <IPAddressRegion />
  <IPAddressCountry />
  <IPAddressCountryISO2 />
  <IPAddressCountryISO3 />
  <IPAddressCertainty />
  <IPAddressISP />
  <IPAddressNetblockOwner />
  <IPAddressIsProxy />
  <IPAddressProxyType />
  <IPAddressErrorDesc>IP Address appears to belong to a private/local network.</IPAddressErrorDesc>
  <IPAddressErrorCode>3</IPAddressErrorCode>
 </Lead>

Frequently Asked Questions

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/le/LeadEnhancement.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.

How often do you update your data?

Address data is updated monthly. Phone and IP data is updated daily. Email data is not updated, it is checked dynamically (we test the email at the time of the request).

Can DOTS Lead Enhancement give me the information for Canadian Leads?

Yes – normally. Our dataset for Canada isn't as extensive as our dataset for the US, but DOTS Lead Enhancement returns information for Canadian phone numbers and addresses.

Where do you get your address information?

We gather our data from many various sources. The short answer is the US Postal Service.

What does the address error "Multiple addresses match." mean? How do I get a single result?

"Multiple addresses match." means that LE found the address, but couldn't resolve it from other addresses that were very similar, typically because of directional elements. For example, if you validate "123 Main street, Anytown, CA", but in Anytown, CA, there is only a "West Main street" and an "East Main street", then this will result in a "Multiple Addresses Match". You will need to specify either West Main or East Main as the street name to get a corrected, single address. There are other cases in which "multiple addresses match" will occur, but are rare and often have to do with a difference in zip+4, or suite numbers.

I got an "Insufficient address data" error from my address. What does that mean?

This error is a catchall for gross errors in the input address. It generally means that the address was too incomplete to piece together or too messy to parse out into identifiable parts.

DOTS Lead Enhancement doesn't return any contact data for my phone number!

This service was not designed to return contact information. It returns only basic carrier level information. If you are interested in a service that does return additional phone contact data, please see DOTS Lead Enhancement Plus. DOTS Lead Enhancement Plus is a premium service that adds some additional data points including the phone contact as well as appending potential alternative phone numbers to a lead. To find out more information, contact your sales rep or look at the following link: https://www.serviceobjects.com/products/lead-validation-verification-solutions/lead-enhancement-plus

Can DOTS Lead Enhancement give me the information for a disconnected number?

No, this is not currently available in this service. 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.This service only does basic phone checks and will not do any disconnected testing. The only service that currently does a disconnected number check is our DOTS Lead Validation service. You can find out more about that service by contacting your sales rep or looking at the following link:https://www.serviceobjects.com/products/composite/lead-validation

I don't care so much about who is at the phone number. I care more about whether the phone number is real or not. What should I do?

You have several options. You can either check for the presence of exchange data (valid phone numbers always return exchange information) or integrate Service Objects' Phone Exchange web service, which was built expressly for this purpose. Find out more about Phone Exchange here: http://www.serviceobjects.com/products/phone/phone-exchange

Can I get more detail on the possible outcomes for NameNotes?

These fields are designed to notify the user when something strange was found while validating the name component. A celebrity note will be returned if the name matches a known celebrity or character. A vulgar note will be returned if the name matches a vulgar word. This needs to be a match of a vulgar word to one of the names not a part of a name. For example, "Shitake" or "Bass" will not return as vulgar. An example of a nonsensical name would be I. P. Freely. A name that is made of random characters contains combinations of letters or special characters that are not likely to be in a real name. A dictionary word identifies names like "Happy Day" or "Gang Love" that are not likely to be a real name.

Ok, how about EmailNotes?

These fields identify interesting or noteworthy pieces of information about the email address. A catchall server is a mail server that always accepts mail to any box in that domain (*@domain). This helps hide valid email addresses from spammers but makes it difficult to validate whether an email is good or not. A bogus email is an indicator of obviously bogus email addresses such as a@a.comasdf@asdf.com and bgates@microsoft.com. A vulgar email is simply one that contains vulgar words. An email that is established with spammers is one that is known within large lists of a bulk-marketing list. An email is considered an alias if it matches the alias rules for different sites. For example, any email with "+" in it at gmail.com is an alias. Also used to identify disposable emails such as anything@mailinator.com where someone can get a temporary email address. An email made of random characters is one that has an excessive amount of letters that do not seem to mean anything.

What are the types of proxies returned in IPAddressProxyType?

It's not unusual to come across proxies while investigating IP addresses. Proxies are never great because they give the user the ability to hide their location, intended or not. This service returns three types of proxies: PRIVATE, PUBLIC and ANONYMOUS. Private proxies are very common. AOL and MSN internet service users will all have IP's using private proxies. Since these are common and legitimate, they will most likely not be fraudulent. However, having an AOL IP address does allow the user to hide their true location and there is always the potential for fraud. Public proxies are most definitely bad. IP's that have been reported as either hacked computers or are known to have made fraudulent requests are labeled as PUBLIC. IP addresses with the tag ANONYMOUS represent IP's that are intentionally misleading their location. A user can log into a service (providing this proxy) and make requests from there (the service can be anywhere and masks the user's original location). While these types of proxies are not necessarily fraudulent the intent to hide location is inherently very high risk.

I need more information on the output field IsEmailAddressValid what does it mean?

The results of this field are based on several other included results (primarily errors and email notes). A "FALSE" result indicates a high likelihood of a bad email. Any combination of bad DNS, SMTP, mailbox or vulgar, alias, or bogus email addresses will return a "FALSE". This should be considered a strong guess or likely indicator of a bad email and not a guaranteed check. It's definitely possible for someone to have a vulgar word in their normal email address, we just do not think it should be considered a good one. Since all of the elements that make up this check are included in the output, you as the user, are more than welcome to use your own criteria for determining email validity.

Important Note!
A full email mail box check is not performed during the normal run of a DOTS LeadEnhancement transaction because this check can be very time consuming. However, if we happen to know that the email is good or bad, we will include those results.


I'm Not a Programmer. How Do I Use DOTS Lead Enhancement?

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

Conclusion

Service Objects is proud to offer you a free trial of DOTS Lead Enhancement. 



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

If you are interested in purchasing DOTS Lead Enhancement, 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