- C#
- Python
- NodeJS
Phone Append 2 C# Code Snippet
using System;
using System.Threading.Tasks;
using PA2Reference;
namespace phone_append_2_dot_net.SOAP
{
/// <summary>
/// Provides functionality to call the ServiceObjects PhoneAppend2 (PA2) SOAP service's PhoneAppend operation,
/// retrieving phone number information for a contact based on provided inputs with fallback to a backup endpoint for reliability in live mode.
/// </summary>
public class PhoneAppendValidation
{
private const string LiveBaseUrl = "https://sws.serviceobjects.com/PA2/api.svc/soap";
private const string BackupBaseUrl = "https://swsbackup.serviceobjects.com/PA2/api.svc/soap";
private const string TrialBaseUrl = "https://trial.serviceobjects.com/PA2/api.svc/soap";
private readonly string _primaryUrl;
private readonly string _backupUrl;
private readonly int _timeoutMs;
private readonly bool _isLive;
/// <summary>
/// Initializes URLs/timeout/IsLive.
/// </summary>
public PhoneAppendValidation(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>
/// This operation returns the best available phone number match for a given contact, including phone number,
/// name, address, city, state, postal code, residential status, certainty, and line type.
/// </summary>
/// <param name="FullName">The full name of the contact. Optional if FirstName and LastName are provided.</param>
/// <param name="FirstName">The first name of the contact. Optional if FullName is provided.</param>
/// <param name="LastName">The last name of the contact. Optional if FullName is provided.</param>
/// <param name="Address">Address line of the contact. Optional.</param>
/// <param name="City">The city of the contact. Optional if postal code is provided.</param>
/// <param name="State">The state of the contact. Optional if postal code is provided.</param>
/// <param name="PostalCode">The postal code of the contact. Optional if city and state are provided.</param>
/// <param name="LicenseKey">The license key to authenticate the API request.</param>
public async Task<PhoneInfoResponse> PhoneAppendAsync(string FullName, string FirstName, string LastName, string Address, string City, string State, string PostalCode, string LicenseKey)
{
PhoneAppend2Client clientPrimary = null;
PhoneAppend2Client clientBackup = null;
try
{
// Attempt Primary
clientPrimary = new PhoneAppend2Client();
clientPrimary.Endpoint.Address = new System.ServiceModel.EndpointAddress(_primaryUrl);
clientPrimary.InnerChannel.OperationTimeout = TimeSpan.FromMilliseconds(_timeoutMs);
PhoneInfoResponse response = await clientPrimary.PhoneAppendAsync(
FullName, FirstName, LastName, Address, City, State, PostalCode, LicenseKey).ConfigureAwait(false);
if (_isLive && !ValidResponse(response))
{
throw new InvalidOperationException("Primary endpoint returned null or a fatal TypeCode=3 error for PhoneAppend");
}
return response;
}
catch (Exception primaryEx)
{
try
{
clientBackup = new PhoneAppend2Client();
clientBackup.Endpoint.Address = new System.ServiceModel.EndpointAddress(_backupUrl);
clientBackup.InnerChannel.OperationTimeout = TimeSpan.FromMilliseconds(_timeoutMs);
return await clientBackup.PhoneAppendAsync(
FullName, FirstName, LastName, Address, City, State, PostalCode, 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?.CloseAsync().GetAwaiter().GetResult();
}
}
finally
{
clientPrimary?.CloseAsync().GetAwaiter().GetResult();
}
}
private static bool ValidResponse(PhoneInfoResponse response)
{
return (response?.Error == null || response.Error.TypeCode != "3");
}
}
}
Phone Append 2 Python Code Snippet
from suds.client import Client
from suds import WebFault
from suds.sudsobject import Object
from typing import Optional
class PhoneAppendSoap:
def __init__(self, license_key: str, is_live: bool = True, timeout_ms: int = 15000):
"""
license_key: Service Objects PA2 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 = timeout_ms / 1000.0
self.license_key = license_key
# WSDL URLs
self._primary_wsdl = (
"https://sws.serviceobjects.com/PA2/api.svc?wsdl"
if is_live
else "https://trial.serviceobjects.com/PA2/api.svc?wsdl"
)
self._backup_wsdl = (
"https://swsbackup.serviceobjects.com/PA2/api.svc?wsdl"
if is_live
else "https://trial.serviceobjects.com/PA2/api.svc?wsdl"
)
def get_phone_append(
self,
full_name: Optional[str] = None,
first_name: Optional[str] = None,
last_name: Optional[str] = None,
address: Optional[str] = None,
city: Optional[str] = None,
state: Optional[str] = None,
postal_code: Optional[str] = None
) -> Object:
"""
Calls the PhoneAppend SOAP API to retrieve a phone number for a given residential contact.
Parameters:
full_name: The full name of the contact. Optional if first_name and last_name are provided.
first_name: The first name of the contact. Optional if full_name is provided.
last_name: The last name of the contact. Optional if full_name is provided.
address: Address line of the contact. Optional.
city: The city of the contact. Optional.
state: The state of the contact. Optional.
postal_code: The postal code of the contact. Optional.
license_key: Your ServiceObjects license key.
is_live: Determines whether to use the live or trial servers.
timeout_ms: Timeout, in milliseconds, for the call to the service.
Returns:
suds.sudsobject.Object: SOAP response containing phone information or error details.
Raises:
RuntimeError: If both primary and backup endpoints fail or return invalid responses.
"""
# Common kwargs for both calls
call_kwargs = dict(
FullName=full_name,
FirstName=first_name,
LastName=last_name,
Address=address,
City=city,
State=state,
PostalCode=postal_code,
LicenseKey=self.license_key,
)
# Attempt primary
try:
client = Client(self._primary_wsdl)
response = client.service.PhoneAppend(**call_kwargs)
# If response invalid or Error.TypeCode == "3", 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)
response = client.service.PhoneAppend(**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)
Phone Append 2 NodeJS Code Snippet
import { soap } from 'strong-soap';
/**
* <summary>
* A class that provides functionality to call the ServiceObjects PhoneAppend2 (PA2) SOAP service's PhoneAppend endpoint,
* retrieving phone number information for a contact based on provided inputs with fallback to a backup endpoint for reliability in live mode.
* </summary>
*/
class PhoneAppendSoap {
/**
* <summary>
* Initializes a new instance of the PhoneAppendSoap class with the provided input parameters,
* setting up primary and backup WSDL URLs based on the live/trial mode.
* </summary>
* @param {string} FullName - The full name of the contact. Optional if FirstName and LastName are provided.
* @param {string} FirstName - The first name of the contact. Optional if FullName is provided.
* @param {string} LastName - The last name of the contact. Optional if FullName is provided.
* @param {string} Address - Address line of the contact. Optional.
* @param {string} City - The city of the contact. Optional if postal code is provided.
* @param {string} State - The state of the contact. Optional if postal code is provided.
* @param {string} PostalCode - The postal code of the contact. Optional if city and state are provided.
* @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, FirstName, LastName, Address, City, State, PostalCode, LicenseKey, isLive = true, timeoutSeconds = 15) {
this.args = {
FullName,
FirstName,
LastName,
Address,
City,
State,
PostalCode,
LicenseKey
};
this.isLive = isLive;
this.timeoutSeconds = timeoutSeconds;
this.LiveBaseUrl = 'https://sws.serviceobjects.com/PA2/api.svc?wsdl';
this.BackupBaseUrl = 'https://swsbackup.serviceobjects.com/PA2/api.svc?wsdl';
this.TrialBaseUrl = 'https://trial.serviceobjects.com/PA2/api.svc?wsdl';
this._primaryWsdl = this.isLive ? this.LiveBaseUrl : this.TrialBaseUrl;
this._backupWsdl = this.isLive ? this.BackupBaseUrl : this.TrialBaseUrl;
}
/**
* <summary>
* Asynchronously calls the PhoneAppend 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 phone number 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 PhoneAppend 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.PhoneAppend(args, (err, result) => {
const response = result?.PhoneAppendResult;
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 { PhoneAppendSoap };