- C#
- Python
- NodeJS
Lead Validation C# Code Snippet
using System;
using System.Threading.Tasks;
using LVReference;
namespace lead_validation_dot_net.SOAP
{
/// <summary>
/// Provides functionality to call the ServiceObjects Lead Validation (LV) SOAP service's ValidateLead_V3 operation,
/// retrieving lead validation information for a given US or Canada lead with fallback to a backup endpoint for reliability in live mode.
/// </summary>
public class ValidateLeadV3Validation
{
private const string LiveBaseUrl = "https://sws.serviceobjects.com/LV/soap.svc/SOAP";
private const string BackupBaseUrl = "https://swsbackup.serviceobjects.com/LV/soap.svc/SOAP";
private const string TrialBaseUrl = "https://trial.serviceobjects.com/LV/soap.svc/SOAP";
private readonly string _primaryUrl;
private readonly string _backupUrl;
private readonly int _timeoutMs;
private readonly bool _isLive;
/// <summary>
/// Initializes URLs, timeout, and IsLive.
/// </summary>
public ValidateLeadV3Validation(bool isLive)
{
_timeoutMs = 10000;
_isLive = isLive;
_primaryUrl = isLive ? LiveBaseUrl : TrialBaseUrl;
_backupUrl = isLive ? BackupBaseUrl : TrialBaseUrl;
if (string.IsNullOrWhiteSpace(_primaryUrl))
throw new InvalidOperationException("Primary URL not set.");
if (string.IsNullOrWhiteSpace(_backupUrl))
throw new InvalidOperationException("Backup URL not set.");
}
/// <summary>
/// Input parameters for the ValidateLead_V3 API call. Represents lead details for validation in the US or Canada.
/// </summary>
/// <param name="FullName">The contact’s full name. Optional.</param>
/// <param name="Salutation">Salutation of the contact. Optional.</param>
/// <param name="FirstName">First name of the contact. Optional.</param>
/// <param name="LastName">Last name of the contact. Optional.</param>
/// <param name="BusinessName">The contact’s company. Optional.</param>
/// <param name="BusinessDomain">Website domain associated with the business. Optional.</param>
/// <param name="BusinessEIN">Company Tax Number for US leads. Optional.</param>
/// <param name="Address1">Address line 1 of the contact or business address. Optional.</param>
/// <param name="Address2">Address line 2 of the contact or business address. Optional.</param>
/// <param name="Address3">Address line 3 of the contact or business address. Optional.</param>
/// <param name="Address4">Address line 4 of the contact or business address. Optional.</param>
/// <param name="Address5">Address line 5 of the contact or business address. Optional.</param>
/// <param name="Locality">The city of the contact’s postal address. Optional.</param>
/// <param name="AdminArea">The state or province of the contact’s postal address. Optional.</param>
/// <param name="PostalCode">The zip or postal code of the contact’s postal address. Optional.</param>
/// <param name="Country">The country of the contact’s postal address. Optional.</param>
/// <param name="Phone1">The contact’s primary phone number. Optional.</param>
/// <param name="Phone2">The contact’s secondary phone number. Optional.</param>
/// <param name="Email">The contact’s email address. Optional.</param>
/// <param name="IPAddress">The contact’s IP address in IPv4. Optional.</param>
/// <param name="Gender">The contact’s gender ("Male", "Female", "Neutral"). Optional.</param>
/// <param name="DateOfBirth">The contact’s date of birth. Optional.</param>
/// <param name="UTCCaptureTime">The time the lead was submitted. Optional.</param>
/// <param name="OutputLanguage">Language for some output information. Optional.</param>
/// <param name="TestType">The type of validation to perform. Required.</param>
/// <param name="LicenseKey">The license key to authenticate the API request. Required.</param>
public async Task<ContactInternational> ValidateLead_V3Async(
string FullName, string Salutation, string FirstName, string LastName,
string BusinessName, string BusinessDomain, string BusinessEIN,
string Address1, string Address2, string Address3, string Address4, string Address5,
string Locality, string AdminArea, string PostalCode, string Country,
string Phone1, string Phone2, string Email, string IPAddress,
string Gender, string DateOfBirth, string UTCCaptureTime,
string OutputLanguage, string TestType, string LicenseKey)
{
LVSoapServiceClient clientPrimary = null;
LVSoapServiceClient clientBackup = null;
try
{
// Attempt Primary
clientPrimary = new LVSoapServiceClient();
clientPrimary.Endpoint.Address = new System.ServiceModel.EndpointAddress(_primaryUrl);
clientPrimary.InnerChannel.OperationTimeout = TimeSpan.FromMilliseconds(_timeoutMs);
ContactInternational response = await clientPrimary.ValidateLead_V3Async(
FullName, Salutation, FirstName, LastName, BusinessName, BusinessDomain, BusinessEIN,
Address1, Address2, Address3, Address4, Address5, Locality, AdminArea, PostalCode, Country,
Phone1, Phone2, Email, IPAddress, Gender, DateOfBirth, UTCCaptureTime, OutputLanguage, TestType, LicenseKey)
.ConfigureAwait(false);
if (_isLive && !IsValid(response))
{
throw new InvalidOperationException("Primary endpoint returned null or a fatal TypeCode=3 error for ValidateLead_V3");
}
return response;
}
catch (Exception primaryEx)
{
try
{
clientBackup = new LVSoapServiceClient();
clientBackup.Endpoint.Address = new System.ServiceModel.EndpointAddress(_backupUrl);
clientBackup.InnerChannel.OperationTimeout = TimeSpan.FromMilliseconds(_timeoutMs);
return await clientBackup.ValidateLead_V3Async(
FullName, Salutation, FirstName, LastName, BusinessName, BusinessDomain, BusinessEIN,
Address1, Address2, Address3, Address4, Address5, Locality, AdminArea, PostalCode, Country,
Phone1, Phone2, Email, IPAddress, Gender, DateOfBirth, UTCCaptureTime, OutputLanguage, TestType, LicenseKey)
.ConfigureAwait(false);
}
catch (Exception backupEx)
{
throw new InvalidOperationException(
$"Both primary and backup endpoints failed.\n" +
$"Primary error: {primaryEx.Message}\n" +
$"Backup error: {backupEx.Message}");
}
finally
{
clientBackup?.Close();
}
}
finally
{
clientPrimary?.Close();
}
}
private static bool IsValid(ContactInternational response) => response?.Error == null || response.Error.TypeCode != "3";
}
}
Lead Validation Python Code Snippet
from suds.client import Client
from suds import WebFault
from suds.sudsobject import Object
class ValidateLeadV3Soap:
def __init__(self, license_key: str, is_live: bool = True, timeout_ms: int = 15000):
"""
Parameters:
license_key: Service Objects LV license key.
is_live: Whether to use live or trial endpoints.
timeout_ms: SOAP call timeout in milliseconds.
"""
self.is_live = is_live
self._timeout_s = timeout_ms / 1000.0
self.license_key = license_key
# WSDL URLs
self._primary_wsdl = (
"https://sws.serviceobjects.com/lv/soap.svc?wsdl"
if is_live
else "https://trial.serviceobjects.com/lv/soap.svc?wsdl"
)
self._backup_wsdl = (
"https://swsbackup.serviceobjects.com/lv/soap.svc?wsdl"
if is_live
else "https://trial.serviceobjects.com/lv/soap.svc?wsdl"
)
def validate_lead_v3(self,
full_name: str,
salutation: str,
first_name: str,
last_name: str,
business_name: str,
business_domain: str,
business_ein: str,
address1: str,
address2: str,
address3: str,
address4: str,
address5: str,
locality: str,
admin_area: str,
postal_code: str,
country: str,
phone1: str,
phone2: str,
email: str,
ip_address: str,
gender: str,
date_of_birth: str,
utc_capture_time: str,
output_language: str,
test_type: str) -> Object:
"""
Calls the ValidateLead_V3 SOAP API to retrieve lead validation information.
Parameters:
full_name: The contacts full name. Optional.
salutation: Salutation of the contact. Optional.
first_name: First name of the contact. Optional.
last_name: Last name of the contact. Optional.
business_name: The contacts company. Optional.
business_domain: Website domain associated with the business (e.g., "serviceobjects.com"). Optional.
business_ein: Company Tax Number for US leads. Optional.
address1: Address line 1 of the contact or business address. Optional.
address2: Address line 2 of the contact or business address. Optional.
address3: Address line 3 of the contact or business address. Optional.
address4: Address line 4 of the contact or business address. Optional.
address5: Address line 5 of the contact or business address. Optional.
locality: The city of the contacts postal address. Optional.
admin_area: The state or province of the contacts postal address. Optional.
postal_code: The zip or postal code of the contacts postal address. Optional.
country: The country of the contacts postal address. Optional.
phone1: The contacts primary phone number. Optional.
phone2: The contacts secondary phone number. Optional.
email: The contacts email address. Optional.
ip_address: The contacts IP address in IPv4. Optional.
gender: The contacts gender. Optional.
date_of_birth: The contacts date of birth. Optional.
utc_capture_time: The time the lead was submitted. Optional.
output_language: Language for some output information. Optional.
test_type: The type of validation to perform. Required.
Returns:
suds.sudsobject.Object: SOAP response containing lead validation details or error.
Raises:
RuntimeError: If both primary and backup endpoints fail.
ValueError: If the license key is empty or null.
"""
# Common kwargs for both calls
call_kwargs = dict(
FullName=full_name,
Salutation=salutation,
FirstName=first_name,
LastName=last_name,
BusinessName=business_name,
BusinessDomain=business_domain,
BusinessEIN=business_ein,
Address1=address1,
Address2=address2,
Address3=address3,
Address4=address4,
Address5=address5,
Locality=locality,
AdminArea=admin_area,
PostalCode=postal_code,
Country=country,
Phone1=phone1,
Phone2=phone2,
Email=email,
IPAddress=ip_address,
Gender=gender,
DateOfBirth=date_of_birth,
UTCCaptureTime=utc_capture_time,
OutputLanguage=output_language,
TestType=test_type,
LicenseKey=self.license_key,
)
# Attempt primary
try:
client = Client(self._primary_wsdl, timeout=self._timeout_s)
response = client.service.ValidateLead_V3(**call_kwargs)
# If response is None or fatal error code, trigger fallback
if response is None or (hasattr(response, "Error") and response.Error and response.Error.TypeCode == "3"):
raise ValueError("Primary returned no result or Error.TypeCode=3")
return response
except (WebFault, ValueError, Exception) as primary_ex:
# Attempt backup
try:
client = Client(self._backup_wsdl, timeout=self._timeout_s)
response = client.service.ValidateLead_V3(**call_kwargs)
if response is None:
raise ValueError("Backup returned no result")
return response
except (WebFault, Exception) as backup_ex:
msg = (
"Both primary and backup endpoints failed.\n"
f"Primary error: {str(primary_ex)}\n"
f"Backup error: {str(backup_ex)}"
)
raise RuntimeError(msg)
Lead Validation NodeJS Code Snippet
import { soap } from 'strong-soap';
/**
* <summary>
* A class that provides functionality to call the ServiceObjects Lead Validation (LV) SOAP service's ValidateLead_V3 endpoint,
* retrieving lead validation information for a given US or Canada lead with fallback to a backup endpoint for reliability in live mode.
* </summary>
*/
class ValidateLeadV3Soap {
/**
* <summary>
* Initializes a new instance of the ValidateLeadV3Soap class with the provided input parameters,
* setting up primary and backup WSDL URLs based on the live/trial mode.
* </summary>
* @param {string} fullName - The contacts full name (e.g., "Jane Doe"). Optional.
* @param {string} salutation - Salutation of the contact (e.g., "Dr", "Mr"). Optional.
* @param {string} firstName - First name of the contact (e.g., "Jane"). Optional.
* @param {string} lastName - Last name of the contact (e.g., "Doe"). Optional.
* @param {string} businessName - The contacts company (e.g., "Service Objects"). Optional.
* @param {string} businessDomain - Website domain associated with the business (e.g., "serviceobjects.com"). Optional.
* @param {string} businessEIN - Company Tax Number for US leads. Optional.
* @param {string} address1 - Address line 1 of the contact or business address. Optional.
* @param {string} address2 - Address line 2 of the contact or business address. Optional.
* @param {string} address3 - Address line 3 of the contact or business address. Optional.
* @param {string} address4 - Address line 4 of the contact or business address. Optional.
* @param {string} address5 - Address line 5 of the contact or business address. Optional.
* @param {string} locality - The city of the contacts postal address. Optional.
* @param {string} adminArea - The state or province of the contacts postal address. Optional.
* @param {string} postalCode - The zip or postal code of the contacts postal address. Optional.
* @param {string} country - The country of the contacts postal address (e.g., "United States", "US"). Optional.
* @param {string} phone1 - The contacts primary phone number. Optional.
* @param {string} phone2 - The contacts secondary phone number. Optional.
* @param {string} email - The contacts email address. Optional.
* @param {string} ipAddress - The contacts IP address in IPv4. Optional.
* @param {string} gender - The contacts gender ("Male", "Female", "Neutral"). Optional.
* @param {string} dateOfBirth - The contacts date of birth. Optional.
* @param {string} utcCaptureTime - The time the lead was submitted. Optional.
* @param {string} outputLanguage - Language for some output information. Optional.
* @param {string} testType - The type of validation to perform. Required.
* @param {string} licenseKey - Your license key to use the service.
* @param {boolean} isLive - Value to determine whether to use the live or trial servers.
* @param {number} timeoutSeconds - Timeout, in seconds, for the call to the service.
* @throws {Error} Thrown if LicenseKey is empty or null.
*/
constructor(fullName, salutation, firstName, lastName, businessName, businessDomain, businessEIN,
address1, address2, address3, address4, address5, locality, adminArea, postalCode, country,
phone1, phone2, email, ipAddress, gender, dateOfBirth, utcCaptureTime, outputLanguage, testType, licenseKey,
isLive = true, timeoutSeconds = 15) {
this.args = {
fullName, salutation, firstName, lastName, businessName, businessDomain, businessEIN,
address1, address2, address3, address4, address5, locality, adminArea, postalCode, country,
phone1, phone2, email, ipAddress, gender, dateOfBirth, utcCaptureTime, outputLanguage, testType, licenseKey
};
this.isLive = isLive;
this.timeoutSeconds = timeoutSeconds;
this.LiveBaseUrl = 'https://sws.serviceobjects.com/LV/soap.svc?wsdl';
this.BackupBaseUrl = 'https://swsbackup.serviceobjects.com/LV/soap.svc?wsdl';
this.TrialBaseUrl = 'https://trial.serviceobjects.com/LV/soap.svc?wsdl';
this._primaryWsdl = this.isLive ? this.LiveBaseUrl : this.TrialBaseUrl;
this._backupWsdl = this.isLive ? this.BackupBaseUrl : this.TrialBaseUrl;
}
/**
* <summary>
* Asynchronously calls the ValidateLead_V3 SOAP endpoint, attempting the primary endpoint
* first and falling back to the backup if the response is invalid (Error.TypeCode == '3') in live mode
* or if the primary call fails.
* </summary>
* @returns {Promise<Object>} A promise that resolves to an object containing lead validation details or an error.
* @throws {Error} Thrown if both primary and backup calls fail, with detailed error messages.
*/
async invokeAsync() {
try {
const primaryResult = await this._callSoap(this._primaryWsdl, this.args);
if (this.isLive && !this._isValid(primaryResult)) {
console.warn("Primary returned Error.TypeCode == '3', falling back to backup...");
const backupResult = await this._callSoap(this._backupWsdl, this.args);
return backupResult;
}
return primaryResult;
} catch (primaryErr) {
try {
const backupResult = await this._callSoap(this._backupWsdl, this.args);
return backupResult;
} catch (backupErr) {
throw new Error(`Both primary and backup calls failed:\nPrimary: ${primaryErr.message}\nBackup: ${backupErr.message}`);
}
}
}
/**
* <summary>
* Performs a SOAP service call to the specified WSDL URL with the given arguments,
* creating a client and processing the response into an object.
* </summary>
* @param {string} wsdlUrl - The WSDL URL of the SOAP service endpoint (primary or backup).
* @param {Object} args - The arguments to pass to the ValidateLead_V3 method.
* @returns {Promise<Object>} A promise that resolves to an object containing the SOAP response data.
* @throws {Error} Thrown if the SOAP client creation fails, the service call fails, or the response cannot be parsed.
*/
_callSoap(wsdlUrl, args) {
return new Promise((resolve, reject) => {
soap.createClient(wsdlUrl, { timeout: this.timeoutSeconds * 1000 }, (err, client) => {
if (err) return reject(err);
client.ValidateLead_V3(args, (err, result) => {
const response = result?.ValidateLead_V3Result;
try {
if (!response) {
return reject(new Error("SOAP response is empty or undefined."));
}
resolve(response);
} catch (parseErr) {
reject(new Error(`Failed to parse SOAP response: ${parseErr.message}`));
}
});
});
});
}
/**
* <summary>
* Checks if a SOAP response is valid by verifying that it exists and either has no Error object
* or the Error.TypeCode is not equal to '3'.
* </summary>
* @param {Object} response - The response object to validate.
* @returns {boolean} True if the response is valid, false otherwise.
*/
_isValid(response) {
return response && (!response.Error || response.Error.TypeCode !== '3');
}
}
export { ValidateLeadV3Soap };