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

Introduction

DOTS NCOA Live is a public XML Web service that uses the USPS's Change of Address (COA) data to determine if, and to where, a person has moved.

This information is only available if the resident has given the USPS their forwarding address; as such, this service is to be used for mailing purposes only.

In addition to move information, this service also standardizes the input address, appends Zip+4 data, and includes additional meta-data about the move-to address such as whether it is currently vacant, whether the address qualifies for pre-sort discounts, and general information about address deliverability.

DOTS NCOA Live provides summary reports as required by the USPS. The CASS Summary Report, and the NCOALink Summary Reports both return data such as how many records were processed, how many were Zip+4 encoded, etc.

Usage Overview

DOTS NCOA Live is a little different than our other services. With our other services, you send a single set of data (Ex: Address, City, State, Zip) and get back a single response.

This service is actually more of a batch service that also allows for single transactions. As such, rather than send an Address, a City, a State, and a Zip, you instead send an array of Address objects all at once in one HTTP request.

In addition, you can (and must) associate all transactions with a "Job" that is open. Think of a "Job" as a batch that stays open all week and waits to receive addresses for processing. You can create multiple "Jobs" during the week and apply transactions to any of them. When you're done, you can get report data for individual Jobs.

Here is a step-by-step overview of how to use this service:

  1. Create a Job
    1. Build an array of 100-500 addresses (100 minimum to create job)
    2. Create a personalized JobId (can be almost any alpha-numeric string of less than 50 characters)
    3. Submit the addresses, JobId, and License Key to the "RunNCOA Live" operation.
  2. Run more transactions against your personalized JobId
    1. Once the Job is created, you can run single transactions or batches of up to 500 all at once through the "RunNCOA Live" operation.
  3. Close the Job by running a report
    1. Calling either "GetCASSSummaryReport" or "GetNCOALinkSummaryReport" will close your job and return report statistics.
    2. These statistics will be available at any time for up to 3 months.
    3. Transactions may no longer be run against that JobId
  4. Go back to Step 1 and repeat with a new JobId.

NOTE: All client jobs are closed on Sunday at 11:55pm. New jobs must be created before using the service again. This is due to restrictions put in place by the USPS that all jobs be at least 100 records, and that all jobs use the most up-to-date NCOA data (released weekly).

Integration


Web services are methods that integrate with other applications via the web, and encapsulate tricky business logic.  Web services are too large 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.

NCOA Live is a public XML web service that supports SOAP, POST, and GET operations.  Note that due to the nature of the primary operation (RunNCOA Live), only SOAP is supported. The reporting operations support all three.

The host path, or physical location of the web service is here:
https://trial.serviceobjects.com/nl/NCOA Live.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/nl/NCOALive.asmx?WSDL

This XML 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 NCOA Live, you can provide this one. Every web service has "operations" that it offers to subscribers – methods that do different work and return different output. Examining the link above, you will notice several of these operations available, which are described in detail later on. Each of these operations will be described in detail later in this document.

Code Snippets




NCOA Live C# Code Snippet
//Add a service to your application https://trial.serviceobjects.com/nl/ncoalive.asmx?WSDL
DOTSNCOALive NCOAClient_Primary = new DOTSNCOALive();
NCOAAddressResponse response = NCOAClient_Primary .RunNCOALive(addresses, JobId, LicenseKey);
		
if (response.Error != null)
{
	//Process Error
}
else
{
	//Process Response		
}


NCOA Live Java Code Snippet
NCOAResult validatedInfo = null;
Error error = null;
// Create soap request
DOTSNCOALiveLocator locator = new DOTSNCOALiveLocator();
// use ssl
locator.setDOTSNCOALiveSoapEndpointAddress("https://trial.serviceobjects.com/nl/ncoalive.asmx?WSDL");
DOTSNCOALiveSoap soap = locator.getDOTSNCOALiveSoap();
soap.setTimeout(5000);
validatedInfo = soap.runNCOALive(addresses, jobId, key);
error = validatedInfo.getError();
if(resp == null || (error != null && error.getTypeCode() == "3"))
{
	throw new Exception();
}
 
//Process Results
if(error == null){
	//DOTS NCOA Live Results	
}
//Process Errors
else{
	//DOTS NCOA Live Error Results	
}


NCOA Live PHP Code Snippets
<?php
// Set these values per web service <as needed>
$wsdlUrl = "https://trial.serviceobjects.com/nl/ncoalive.asmx?WSDL";

$params['Addresses'] 	= $Addresses;
$params['JobId'] 		= $JobId;
$params['LicenseKey'] 	= $LicenseKey;

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


NCOA Live RoR Code Snippets
		#Formats inputs into a hash to pass to Soap Client
		#Hash Keys must be named as they are shown here.
		message = 	{
						"LicenseKey" => @request.licensekey,
					}

		#Implemented to make the code more readable when accessing the hash			
		@ncoaresponse = :get_job_summary_report_response
		@ncoaresult = :get_job_summary_report_result
		@ncoajobs = :jobs
		@ncoajobinfo = :job_info
		@ncoaerror = :error

		#Set Primary and Backup URLs here as needed
		dotsNCOAPrimary = "http://trial.serviceobjects.com/nl/NCOALive.asmx?WSDL"
		dotsNCOABackup = "http://trial.serviceobjects.com/nl/NCOALive.asmx?WSDL"
		@displaydata = Hash.new()
		begin
			#initializes the soap client. The convert request keys global is necessary to receive a response from the service.
			client = Savon.client(wsdl: dotsNCOAPrimary)
			#Calls the operation with given inptus and converts response to a hash.
			response = client.call(:get_job_summary_report, 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: dotsNCOABackup)
			#Sets the response to the backclient call to the operation and converts response to a hash.
			response = backupclient.call(:get_job_summary_report, message: message).to_hash
			processresults(response)

			#If backup url failed, this will display the error received from the server
			rescue Savon::Error =>error
			end
		end
	end
	private 
	def processresults(response)	
		#Processes Error Response from soap Client		
		#Processes Valid response from soap client				
		
	end


NCOA Live Python Code Snippet
 
    mLicenseKey = LicenseKey.get()
    if mLicenseKey is None or mLicenseKey == "":
        mLicenseKey = " "
    #Set the primary and backup URLs as needed
    primaryURL = 'http://trial.serviceobjects.com/nl/NCOALive.asmx?WSDL'
    backupURL = 'http://trial.serviceobjects.com/nl/NCOALive.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.GetJobSummaryReport(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.GetJobSummaryReport(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)


NCOA ColdFusion Code Snippet
<!--Makes Request to web service --->
<cfscript>
		try
		{
			if (isDefined("form.Action") AND Action neq "")
			{
				wsresponse = CreateObject("webservice", "http://ws.serviceobjects.com/nl/ncoalive.asmx?WSDL");							  
				outputs = wsresponse.getJobSummaryReport("#LicenseKey#");
				writedump(outputs.getError());
			}
		}
	catch(any Exception){
		try
			{
				if (isDefined("form.Action") AND Action neq "")
				{
					wsresponse = CreateObject("webservice", "http://ws.serviceobjects.com/nl/ncoalive.asmx?WSDL");							  
					outputs = wsresponse.getJobSummaryReport("#LicenseKey#");
				}
			}
			catch(any Exception)	{
		  		 writeoutput("An Error Has Occured. Please Reload and try again");		  		 
		 		}
	    }
</cfscript>


NCOA VB Code Snippet
Try
	Dim ws As New NCOA.DOTSNCOALiveSoapClient
	Dim response As NCOA.JobSummaryReportResponse

	response = ws.GetJobSummaryReport(LicenseKey.Text)
	If (response.Error Is Nothing) Then
		ProcessValidResponse(response)
	Else
		ProcessErrorResponse(response.Error)
	End If

Catch er As Exception
	Try
		''Set the primary and backup service references as necessary
		Dim wsbackup As New NCOA.DOTSNCOALiveSoapClient
		Dim response As NCOA.JobSummaryReportResponse
		response = wsbackup.GetJobSummaryReport(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


NCOA Apex Code Snippet
wwwServiceobjectsCom.JobSummaryReportResponse result;
try{
wwwServiceobjectsCom.DOTSNCOALiveSoap client = new wwwServiceobjectsCom.DOTSNCOALiveSoap();
result = client.GetJobSummaryReport([LicenseKey]);
}
catch(Exception ex){
 //If the first request failed try the failover endpoint
wwwServiceobjectsCom.DOTSNCOALiveSoap backupClient = new wwwServiceobjectsCom.DOTSNCOALiveSoap();
//The backup environment will be provided to you upon purchasing a production license key
backupClient.endpoint_x = 'http://trial.serviceobjects.com/NCOALive/api.svc/soap';
result = backupClient.GetJobSummaryReport([LicenseKey]);
}


NCOA 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">'+
				   '<GetJobSummaryReport xmlns="http://www.serviceobjects.com">'+
				   '<LicenseKey>' + @key + '</LicenseKey>'+
				   '</GetJobSummaryReport>'+
				   '</s:Body>'+
				   '</s:Envelope>'
SET @requestLength = LEN(@requestBody)
	--If a production key is purchased, this will execute the failover 
IF @isLiveKey = 1
BEGIN
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'http://ws.serviceobjects.com/nl/ncoalive.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', '"http://www.serviceobjects.com/GetJobSummaryReport"'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
	EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
	EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
	EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'http://wsbackup.serviceobjects.com/nl/ncoalive.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', '"http://www.serviceobjects.com/GetJobSummaryReport"'
		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



NCOA Live Java Rest Code Snippet
<%  
		
try{
	String licensekey = request.getParameter("licensekey");
	URL url = null;
	licensekey = URLEncoder.encode(licensekey,"UTF-8").replaceAll("\\+", "%20");
	
	String mainurl = "https://trial.serviceobjects.com/nl/ncoalive.asmx/GetJobSummaryReport?LicenseKey=" + licensekey;
	String backupurl = "https://trial.serviceobjects.com/nl/ncoalive.asmx/GetJobSummaryReport?LicenseKey=" + licensekey;

	
	Gson gson = new Gson();
	HttpsURLConnection conn = null;
	url = new URL(mainurl);
	
	
	System.out.println(url);
	conn = (HttpsURLConnection) url.openConnection();
	conn.setConnectTimeout(5000);
	conn.setRequestMethod("GET");
	conn.setRequestProperty("Accept", "application/json");

	if (conn.getResponseCode() != 200) {
		throw new RuntimeException("Failed : HTTP error code : "
				+ conn.getResponseCode());
	}

	BufferedReader br = new BufferedReader(new InputStreamReader(
		(conn.getInputStream())));
	StringBuilder sb = new StringBuilder();
	String output; 
	//System.out.println("info from the server \n");
	while ((output = br.readLine()) != null) {
		sb.append(output);
		//System.out.println(output);
	}
	
		JSONObject results = XML.toJSONObject(sb.toString());
		JSONObject outputs = results.getJSONObject("JobSummaryReportResponse");
		
%>


NCOA Live 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("http://trial.serviceobjects.com/nl/ncoalive.asmx/GetJobSummaryReport?LicenseKey=" + licensekey)
backupURL = URI.encode("http://trial.serviceobjects.com/nl/ncoalive.asmx/GetJobSummaryReport?LicenseKey=" + licensekey)

#These are set to access the hash that is returned
@ncoaresponse ="JobSummaryReportResponse"
@ncoajobs = "Jobs"
@ncoainfo = "JobInfo"
@ncoaerror = "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


NCOA Live Python Rest Code Snippet
 
#The Requests package allows the user to format the path parameters like so instead of having to manually insert them into the URL
primaryURL = 'http://trial.serviceobjects.com/nl/noalive.asmx/GetJobSummaryReport?'
backupURL = 'http://trial.serviceobjects.com/nl/ncoalive.asmx/GetJobSummaryReport?'
inputs = {'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['JobSummaryReportResponse']:
        #loops through the response from the service and prints the values to the screen.
        for key, value in outputs['JobSummaryReportResponse']['Error'].iteritems():
            Label(swin.window, text=str(key) + " : " + str(value)).pack()
    else:
        #Prints a title with the JobSummaryReport number and the resulting details for the job number
        for i in range(0, len(outputs['JobSummaryReportResponse']['Jobs']['JobInfo'])):
            Label(swin.window, font='bold', text="Job Summary #"+str(i+1)).pack()
            for key, value in outputs['JobSummaryReportResponse']['Jobs']['JobInfo'][i].iteritems():
                Label(swin.window, text=str(key) + " : " + str(value)).pack()
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['JobSummaryReportResponse']:
            #loops through the response from the service and prints the values to the screen.
            for key, value in outputs['JobSummaryReportResponse']['Error'].iteritems():
                Label(swin.window, text=str(key) + " : " + str(value)).pack()
        else:
            #Prints a title with the JobSummaryReport number and the resulting details for the job number
            for i in range(0, len(outputs['JobSummaryReportResponse']['Jobs']['JobInfo'])):
                Label(swin.window, font='bold', text="Job Summary #"+str(i+1)).pack()
                for key, value in outputs['JobSummaryReportResponse']['Jobs']['JobInfo'][i].iteritems():
                    Label(swin.window, text=str(key) + " : " + str(value)).pack()


NCOA ColdFusion Rest Code Snippet
<!--Makes Request to web service --->
<cfIf isDefined("form.Action") AND Action neq ""  >
	<cftry>
		<cfset primaryURL = "http://trial.serviceobjects.com/nl/ncoalive.asmx/GetJobSummaryReport?LicenseKey=#LicenseKey#">
		<cfhttp url="#primaryURL#" method="get" result="response">
		<cfset outputs = XmlParse(response.FileContent)>
	<cfcatch >
		<cftry>
			<cfset backupURL = "http://trial.serviceobjects.com/nl/ncoalive.asmx/GetJobSummaryReport?LicenseKey=#LicenseKey#">
			<cfhttp url="#backupURL#" method="get" result="response">
			<cfset outputs = XmlParse(outputs.FileContent)>				
			<cfcatch >
				<cfoutput >
					The Following Error Occured: #response.StatusCode#
				</cfoutput>
			</cfcatch>
		</cftry>
	</cfcatch>
	</cftry>
</cfif>


NCOA VB Rest Code Snippet
'encodes the URLs for the get Call. Set the primary and back urls as necessary
Dim primaryurl As String = "http://trial.serviceobjects.com/nl/ncoalive.asmx/GetJobSummaryReport?LicenseKey=" & licensekey
Dim backupurl As String = "http://trial.serviceobjects.com/nl/ncoalive.asmx/GetJobSummaryReport?LicenseKey=" & licensekey
Dim wsresponse As NCOAResponse.JobSummaryReportResponse = httpGet(primaryurl)

'checks if a response was returned from the service, uses the backup url if response is null or a fatal error occured.
If wsresponse Is Nothing OrElse (wsresponse.[Error] IsNot Nothing AndAlso wsresponse.[Error].TypeCode = "3") Then
	wsresponse = httpGet(backupurl)
End If
If wsresponse.[Error] IsNot Nothing Then
	ProcessErrorResponse(wsresponse.[Error])
Else
	ProcessSuccessfulResponse(wsresponse)

End If


NCOA TSQL Rest Code Snippet
BEGIN
	SET @sUrl = 'http://ws.serviceobjects.com/nl/ncoalive.asmx/GetJobSummaryReport?LicenseKey=' + @key
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'Get', @sUrl, false
	EXEC sp_OAMethod @obj, 'send'
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		SET @sBackupUrl = 'http://wsbackup.serviceobjects.com/nl/ncoalive.asmx/GetJobSummaryReport?LicenseKey=' + @key
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'Get', @sBackupUrl, false
		EXEC sp_OAMethod @obj, 'send'
		EXEC sp_OAGetProperty @obj, 'responseText', @response OUT
	END
END

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

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

C#
using System;
using System.Collections.Generic;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.IO;
using System.Text.RegularExpressions;
using com.serviceobjects.trial;
public partial class _Default : System.Web.UI.Page 
{
    protected void Page_Load(object sender, EventArgs e)
    {
        lblError.Visible = false;
        rptNCOAOutput.Visible = true;
    }
    private void runNCOALive(String inputPath, String JobId, string LicenseKey)
    {
        
        DOTSNCOALive ncoaLive = new DOTSNCOALive();
        NCOAAddressResponse rtn = new NCOAAddressResponse();
        DOTSNCOALive ncoa = new DOTSNCOALive();
        try
        {
            NCOAAddress[] addresses = ReadInputAddressesFromFile(inputPath);
            rtn = ncoa.RunNCOALive(addresses, JobId, LicenseKey);
            if (rtn.Error != null)
            {
                DisplayError(rtn.Error.Desc);
                return;
            }
            List<NCOAResult> res = new List<NCOAResult>(rtn.NCOAResultItem);
            rptNCOAOutput.DataSource = res;
            rptNCOAOutput.DataBind();
        }
        catch (Exception e)
        {
            DisplayError(e.Message);
        }
    } // end function validate address

    public NCOAAddress[] ReadInputAddressesFromFile(string path)
    {
        string BatchContents = File.ReadAllText(path);
        string[] Response = Regex.Split(BatchContents, "\r\n");
        NCOAAddress[] rtn = new NCOAAddress[Response.Length - 1]; //skip header row
        for (int i = 1; i < Response.Length; i++)
        {
            string[] s = Response[i].Split(',');
            NCOAAddress a = new NCOAAddress();
            if (s.Length >= 6)
            {
                a.Name = s[0];
                a.Address = s[1];
                a.Address2 = s[2];
                a.City = s[3];
                a.State = s[4];
                a.Zip = s[5];
            }
            rtn[i - 1] = a;
        }
        return rtn;
    }
    private void DisplayError(string err)
    {
        lblError.Text = err;
        lblError.Visible = true;
        rptNCOAOutput.Visible = false;
    }

    public T GetTypedRepeaterItem<T>(Control TheContainer)
    {
        return (T)((RepeaterItem)TheContainer).DataItem;
    }
    public NCOAResult CastAsNCOAResponse(Control TheContainer)
    {
        NCOAResult rtn = (NCOAResult)(((RepeaterItem)TheContainer).DataItem);
        if (rtn.Error != null && rtn.Error.Desc != null)
        {
            rtn.Diagnostics = new DiagnosticsFields();
            rtn.RawInputAddress = new RawInputAddress();
            rtn.CASSInputAddress = new CASSInputAddress();
            rtn.NCOAMatch = new NCOAMatch();
        }
        else rtn.Error = new Error();
        return rtn;
    }
    protected void Imagebutton1_Click(object sender, ImageClickEventArgs e)
    {
        this.runNCOALive(pathInput.Text, jobIdInput.Text, licenseInput.Text);
    }
}

List of Operations

RunNCOALive (primary operation) – Submit 1-500 name and address records at once and apply it to an open Job via an ID that you created. You will receive an array of addresses that are standardized along with any COA matches that were found.
RunNCOALiveSingleAddress – Submit a single name and address along with an open Job ID. You will receive a result for the single address along with any COA details if a COA match was found. Note that this operation requires an open Job ID, therefore you must first use the RunNCOALive operation to submit a 100 record batch and create a new Job ID before this operation can be used.
GetCASSSummaryReport – Returns all necessary data as part of the USPS's CASS Summary Report. These data include things like total records, total zip+4 encoded, etc.
GetNCOALinkSummaryReport-- Returns all necessary data as part of the USPS's NCOALink Summary Report (also referred to as the "PSR"). These data include things like report completion date, List Name, and also general statistics of the batch.
GetJobSummaryReport – This is a convenience operation which will provide a list of all jobs this key has run or is currently running. This can be used to generate new Job Ids, or for general informational purposes.

Operation Definitions

This document defines the input, output, and behavior of the web service operations in NCOA Live.   

RunNCOALive


This is the primary operation for DOTS NCOA Live and serves to perform 2 essential functions:

  1. Creating new jobs.
  2. Running transactions against existing jobs.

To create a new Job, you must create a JobId, and send a minimum of 100 address records all at once. After this, you may run single transactions or up to 500 at once. The JobId cannot have been previously used by your License Key, and can be almost any string less than 50 characters (ex: integer, current epoch, filename, etc).

Once the Job is created, you can send 1-500 addresses at a time by building an array of NCOAAddress objects containing Name, Address, City, State, and Zip.

The operation will try to find that address, standardize it, and see if the person who lived there has recently moved. If they have moved, and the forwarding address exists, it will be returned. Not all COA matches return forwarding addresses; sometimes the only thing that's known is that they moved.

RunNCOALive Inputs

Name

Type

 

Description

Addresses

NCOAAddress[]

Name

Name of address resident.



Address

The primary address line.



Address2

The secondary address.



City

City name.



State

State abbreviation.



Zip

Zip code.

JobId

String


User-created string to identify an open Job. Can be any string of 50 characters or less. Cannot contain any of the following characters:  \ / * : ? " < > |

LicenseKey  

String


Your license key to use the service. 
Sign up for a free trial key at
https://www.serviceobjects.com/products/address-geocoding/ncoa-live


RunNCOALive Outputs

Parent Object

Child

Values

Description

NameIn


Varies

The raw input name.

RawInputAddress

Address

Varies

The raw input address line.


Address2

Varies

The raw input address2 line.


City

Varies

The raw input city.


State

Varies

The raw input state.


Zip

Varies

The raw input Zip code.

CASSInputAddress

Address

Varies

The standardized address line.


Address2

Varies

The standardized secondary.


City

Varies

The standardized city name.


State

Varies

The standardized state.


Zip

Varies

The standardized Zip+4


USPSFootnotes

Varies

A concatenated string of relevant 2-digit USPS "Footnote" codes that give additional information about the input address.

NCOAMatch

NameMatch

Varies

The name that matched the COA record.


Address

Varies

The primary address line that the resident moved to.


Address2  

Varies

The secondary address line.


City

Varies

The city name.


State

Varies

The state abbreviation.


Zip

Varies

The Zip+4.


CarrierRoute

Varies

The Carrier Route code for the COA address.


BarcodeDigits

Varies

The PostNet barcode for the COA address.


COAFound

"True" or "False"

Whether or not a match was found in the COA data. Does not imply that a valid address could be found.


NCOAReturnCode

Varies

The USPS's NCOALink Return Code providing additional information about the nature of the COA match


NCOAReturnCodeDesc

Varies

Short English description of the COA information. Longer descriptions found below.


ExtendedNCOAReturnCode

(See below)

USPS's Extended NCOA Return Code comprising a series of key/value strings.

Diagnostics

DiscountCode

1-4

A code representing discount level.


DiscountDescription

(See below)

An English description of the discount level.


StatusCode

2-8

A code representing the level of quality of the input address post-validation. Higher is better.


StatusDescription

(See below)

An English description of the level of quality of the input address post-validation.


ServiceFlags

Varies

USPS Service Flags output explains what additional address services were run such as RDI, eLOT, etc

Error

Type

Varies

English description of the error type. See "Error Codes" below.


TypeCode

1, 2, 3, 4

Unique error type code. See "Errors" below.


Desc

Varies

English description of the error. See "Errors" below.


DescCode

Varies

Unique code for the error. See "Errors" below.

JobId


Varies

The JobId sent to the service.


Discount Codes

DiscountCode

DiscountDescription

1

Automation

2

Presort

3

None

4

Unknown

Status Codes

StatusCode

StatusDescription

2

Address not deliverable

3

Address may not be deliverable

4

Address matched and is deliverable, but is vacant

5

Recipient moved without providing a forwarding address

6

Mail being returned for non-specified reasons

7

Address matched and is deliverable

8

Address matched, COA forwarding address found

NCOANotes Codes

NCOANotes

NCOANotesDescShort

NCOANotesDescLong

A

COA Match Found

COA match was found with a forwarding address.

00

No COA Match Found

No COA match was found with given input name, address and matching logic.

01

Foreign Move

Match found, but new address outside USPS delivery area - a new address cannot be provided.

02

Move left no address

Match found, but the new address was not provided to the USPS - a new address cannot be provided.

03

PO BOX Closed, No Forwarding Address

Match found, but the new address was not provided to the USPS - a new address cannot be provided.

04

Street Address With Secondary

A COA was found utilizing the last name and address but the input did not contain a secondary number and the COA contained a secondary number.

05

A New Address Cannot Be Provided

The DPBC represents more than one address - the new address cannot be provided.

06

Middle Name Conflict

More than one COA and the middle names or initials on the COA's are different - new address cannot be provided due to unresolved conflict.

07

Gender Conflict

More than one COA exists and the genders on the COA's are different - new address cannot be provided due to unresolved conflict.

08

Conflicting Instructions

More than one COA exists with differences in the new address - new address cannot be provided due to unresolved conflict.

09

High-rise Default

Family COA with high-rise address ZIP+4 coded to building default - individual name information required for match missing or not match COA.

10

Rural Default

Family COA with Rural Route or Highway Contract address ZIP+4 coded to a route default - individual name information required for match missing or not match COA.

11

Insufficient COA Name

Individual name information on the COA is insufficient to allow a match.

12

Middle Name Test Failed

Input middle name information does not match COA middle name information. - match not allowed - new address cannot be provided.

13

Gender Test Failed

Input gender information does not match COA gender information - match not allowed - new address cannot be provided.

14

New Address Would Not Convert

Address could not be converted to a deliverable address - the new address could not be provided.

15

Individual Name Insufficient

The input does not contain a first name or contains initials only - the individual name information required to make match was missing from input.

16

Secondary Number Discrepancy

Either there is conflicting secondary information or input had secondary information and matched to a family record without secondary information.

17

Other Insufficient Name

Input name is different or not sufficient enough to produce a match.

18

General Delivery

The input record matched to a family record from a General Delivery address - this address type requires an individual name matching to obtain a match.

19

New Address Does Not ZIP+4 Or DPV Confirm

The new address not ZIP+4 coded or new address primary number, not DPV confirmable - the new address could not be provided.

20

Conflicting Directions

Conflicting directions after re-chaining - multiple COA's exist but contain different new addresses.

66

Daily Delete

COA is pending deletion from the master file.

91

Secondary Number Dropped From COA

Matched to an individual COA - the COA contained a secondary number and the input did not contain a secondary number - a new address is provided.

92

Secondary Number Dropped From Input

Matched to an individual COA - the input contained a secondary number and the COA did not contain a secondary number - a new address is provided.


USPS Footnote Codes CASS Zip+4 Certification Footnotes

Footnote code

Description

AA

Input Address Matched to the ZIP+4 file

A1

Input Address Not Matched to the ZIP+4 file


DPV Validation Footnotes

Footnote code

Description

BB

Input Address Matched to DPV (all components)

CC

Primary number matched to DPV, but secondary number not matched

N1

Primary Number Matched to DPV but Address Missing Secondary Number

M1

Primary number missing

M3

Non-postal Primary number invalid

P1

Input Address RR or HC Box number Missing

P3

Address PO, RR, or HC Box number Invalid

F1

Input Address Matched to a Military Address

G1

Input Address Matched to a General Delivery Address

U1

Input Address Matched to a Unique ZIP Code


CMRA-related Footnotes

Footnote code

Description

RR

Input Address Matched to CMRA and PMB designator present

RR1

Input Address Matched to CMRA but PMB designator not present


Extended NCOA Return Code

The Extended NCOA Return Code is a string of key/value tokens separated by spaces. These codes return useful meta-data that you can parse using standard string functions. The return code takes the form of:

TYP=X MED=yyyymm AGE=nn NAM=abc def

Key

Value

TYP

Result Move Type. F, I, or B
"F" – Family
"I" – Individual
"B" -- Business

MED

Move Effectivity Date. Takes the form of yyyymm (e.g. "201201" for January 2012)

AGE

Age, in months, of the NCOA record. Anything older than 18 months will no longer return an NCOA match

NAM

Name associated with the COA match. Same as
CASSInputAddress->NameOut


ServiceFlags

This field describes information about additional USPS services that were run. Takes the form of:

RDI S=xx L=xxx E=sequence C=county_code

Key

Description

RDI

If present, address was marked as a residence by RDI

S

Appears when a SuiteLink lookup attempted.
00 – No Match
A – Record Match

L

Appears when LACSLink lookup attempted.
N00 – No Match
YA – Record Match
Y14 – Record Match, New Address Would not convert at run-time
S92 – Record Match – Secondary Number Dropped from Input Address

E

eLOT sequence code.

C

County code

RunNCOALiveSingleAddress

This operation accepts a single name and address and allows you to perform a single NCOA query using an existing OPEN Job ID.

This operation cannot be used to create a new Job ID, since every new Job ID requires a minimum of 100 records as per USPS requirements.
If you do not have a Job ID that is currently OPEN then you must first use the RunNCOALive operation to create a new Job ID by processing at least 100 records.
Afterwards you may then use the newly created Job ID to process requests using the RunNCOALiveSingleAddress operation.

Unlike the RunNCOALive operation, which is SOAP only, this operation also supports the HTTP GET protocol.
Both the SOAP output and the HTTP GET output are in XML.

RunNCOALiveSingleAddress Inputs

Name

Type

 

Description

Name

String


Name of address resident.

Address

String 


The primary address line.

Address2 

String 


The secondary address.

 City

String


City name.

 State

String 


State abbreviation.

 Zip

String 


Zip code.

JobId

String


User-created string to identify an open Job. Can be any string of 50 characters or less. Cannot contain any of the following characters:  \ / * : ? " < > |

LicenseKey  

String


Your license key to use the service. 
Sign up for a free trial key at
https://www.serviceobjects.com/products/address-geocoding/ncoa-live

RunNCOALiveSingleAddress Output

The RunNCOALiveSingleAddress output is the same as the RunNCOALive output except that only one NCOA result is returned instead of an arrary of NCOA results.
Please refer to the NCOALiveResult Outputs section for output values and descriptions.

GetCASSSummaryReport

The CASS Summary Report (aka "Form 3553") is a form that proves to the USPS that your addresses were run against a certified address validation engine. It contains information about the engine itself, as well as statistics of your job.

Only the CASS-related statistics are contained in this operation. For NCOA stats, see the "GetNCOALinkSummaryReport" operation.

This operation contains just the raw data. A link is provided in the operation that will lead to the blank form which can be filled out with the values from the service. 

NOTE: Running a report for your Job, closes the job to new transactions permanently. Do not run this report until you're finished with the job.

GetCASSSummaryReport Inputs

Name

Type

Description

JobId

String

The client-created ID for your Job.

LicenseKey

String

Your license key to use the service. 
Sign up for a free trial key at
https://www.serviceobjects.com/products/address-geocoding/ncoa-live


GetCASSSummaryReport Outputs

Name

Type

Values

Description

Form 3553 Location*

Total

String

Varies

The total number of records run in this batch.

B.6

Zip4

String

Varies

The total number of Zip+4 records found in this job.

C.a - "Total Coded" Column

Zip5

String

Varies

The total number of 5-digit Zip codes found in this job.

C.d - "Total Coded" Column

CRT

String

Varies

The total number of Carrier Route codes found.

C.e - "Total Coded" Column

AMSVNo

String

Varies

USPS data version number.

B.3.a, B.3.d, B.3.e

Today

String

Date mm/dd/yy

The date the report was run.

B.2.a, B.2.d, B.2.e

C.a, C.d, C.e, C.f - Validation Period "From" Section

TodayP90

String

Date mm/dd/yy

The date 90 days from the date the report was run.

C.e, C.f - Validation Period "To" Section

TodayP180

String

Date mm/dd/yy

The date 180 days from the date the report was run.

C.a - Validation Period "To" Section

TodayP365

String

Date mm/dd/yy

The date 365 days from the date the report was run.

C.d - Validation Period "To" section

HExact

String

Varies

Number of High-Rise Exact records found.

E - "High Rise Exact" section

HDefault

String

Varies

Number of High-Rise Default records found.

E - "High Rise Default" section

RExact

String

Varies

Number of Rural Route Exact records found.

E - "RR Exact" section

RDefault

String

Varies

Number of Rural Route Default records found.

E - "RR Default" section

LACS

String

Varies

Number of records matched through LACSLink.

E - "LACSLink" section

ListName

String

Other (Internal List)

USPS List Id. Static value.

B.4

ListCount

String

1

Number of lists processed in this mailing. Will always be 1.

B.5

Configuration

String

AES

This is the name of the registered configuration used by the engine for validation. Will always be "AES".

A.3, A.12

Version

String

Varies

The version of the certified validation software.

A.2, A.11 - Left Side of Box

ProductName

String

Varies

The name of the certified validation software.

A.2, A.11 - Right Side of Box

MFGName

String

Varies

Manufacturer of the certified validation software.

A.1, A.10

Mailer

String

Varies

Name of the company running this mailing. (Client's company name).

D.3

Address1

String

Varies

Address line 1 of the mailer.

D.3

Address2

String

Varies

Address line 2 of the mailer.

D.3

Address3

String

Varies

Address line 3 of the mailer.

D.3

Processor

String

EZ24x7 iDOTS

The name of the processing engine. Always "EZ24x7 iDOTS".

B.1

eLOT

String

Varies

Number of records matched through eLOT.

C.f - "Total Coded" Section

DPV

String

Varies

Number of records that were DPV coded.

C.a - "Total Coded" Section

EWS

String

Varies

Number of records matched through EWS (Early Warning System)..

E - "EWS" section

RDI

String

Varies

Number of records that were processed through RDI.

-

FormURL

String

Varies

URL for retrieving a blank 3553 PDF form


Error

Type

Varies

English description of the error type. See "Error Codes" below.



TypeCode

1, 2, 3, 4

Unique error type code. See "Errors" below.



Desc

Varies

English description of the error. See "Errors" below.



DescCode

Varies

Unique code for the error. See "Errors" below.


*This column corresponds to the different locations and sections on the 3553 form to enter the values for this service.

GetNCOALinkSummaryReport

The NCOALink Processing Summary Report (aka "PSR") is a report that contains data for a specific list.

NOTE: Running a report for your Job, closes the job to new transactions permanently. Do not run this report until you're finished with the job.

GetNCOALinkSummaryReport Inputs


Name

Type

Description

JobId

String

The client-created ID for your Job.

LicenseKey

String

Your license key to use the service. 
Sign up for a free trial key at
https://www.serviceobjects.com/products/address-geocoding/ncoa-live


GetNCOALinkSummaryReport Outputs


Name

Values

Description

CustomerPAFId

Varies

The PAF Id assigned to the client after registration.

MailerCompanyName

Varies

The name of the registered company.

ListName

Varies

The name of the list.

ProcessingCategory

Varies

(probably always NORMAL)

PreProcessesPerformedFlag

Varies

Flag detailing the type of Pre-processes performed.

ConcurrentProcessesPerformedFlag

Varies

Flag detailing the type of concurrent processes performed.

PostProcessesPerformedFlag

Varies

Flag detailing the type of post-processes performed.

StandardOutputReturnedFlag

Varies

Flag indicating if all output was provided to the client.

MatchingLogicAppliedFlag

Varies

Type of matching logic used (e.g. Individual or Business logic, or both)

DataReturnedFlag

C, F, S

Indicates whether COA data is returned.

ClassOfMail

A-O

Class of mail to be used for mailings produced from customer mailing list

DateProcessingCompleted

YYYYmmdd

Completion date of the batch.

DateListReturnedToCustomer

Varies

Date that list was provided to the client.

TotalNumberOfRecordsProcessed

Varies

Total records processed in batch.

TotalNumberOfRecordsMatchedNCOALink

Varies

Total records that returned NCOA data.

TotalNumberOfRecordsMatchedANKLink

Varies

Total records that returned ANK (Attempted Not Known) data. Return to sender.

TotalNumberOfRecordsZip4Coded

Varies

Total Zip+4 found.

TotalNumberOfRecordsDPVConfirmed

Varies

Total DPV matches found.

TotalNumberOfRecordsMatchedLACSLink

Varies

Total LACSLink matches found.

TotalNumberOfRecordsMatchedSuiteLink

Varies

Total SuiteLink matches found.

MovedNewAddressProvided_00_03

Varies

Total new addresses found that were <= 3 months old.

MovedNewAddressProvided_04_06

Varies

Total new addresses found between 4 and 6 months old.

MovedNewAddressProvided_07_12

Varies

Total new addresses found between 7 and 12 months old.

MovedNewAddressProvided_13_18

Varies

Total new addresses found between 13 and 18 months old.

MovedNewAddressProvided_19_On

Varies

Total new addresses found >= 19 months old.

MovedNoNewAddressProvided_00_03

Varies

Total matches without new addresses provided <= 3 months old.

MovedNoNewAddressProvided_04_06

Varies

Total matches without new addresses provided between 4 and 6 months old.

MovedNoNewAddressProvided_07_12

Varies

Total matches without new addresses provided between 7 and 12 months old.

MovedNoNewAddressProvided_13_18

Varies

Total matches without new addresses provided between 13 and 18 months old.

MovedNoNewAddressProvided_19_On

Varies

Total matches without new addresses provided >= 19 months old.

MovedUnableToProvideNewAddress_00_03

Varies

Total matches with problematic return addresses <= 3 months old.

MovedUnableToProvideNewAddress_04_06

Varies

Total matches problematic return address between 4 and 6 months old.

MovedUnableToProvideNewAddress_07_12

Varies

Total matches problematic return address between 7 and 12 months old.

MovedUnableToProvideNewAddress_13_18

Varies

Total matches problematic return address between 13 and 18 months old.

MovedUnableToProvideNewAddress_19_On

Varies

Total matches problematic return address >= 19 months old.

Error.Type

Varies

English description of the error type. See "Error Codes" below.

Error.TypeCode

1, 2, 3, 4

Unique error type code. See "Errors" below.

Error.Desc

Varies

English description of error. See "Errors" below.

Error.DescCode

Varies

Unique code for the error. See "Errors" below.

GetJobSummaryReport

This operation is a utility operation which gives you information about what jobs your license key has open or closed. Returns in order of starting date.

GetJobSummaryReport Inputs

Name

Type

Description

LicenseKey

String

Your DOTS NCOA Live license key


GetJobSummaryReport Outputs


Name

Child Object

Values

Description

JobInfo

JobId

Varies

The Job Id


Status

"OPEN" or "CLOSED"

Status of the job.


StartDate

mm/dd/yyyy hh:mm:ss AM/PM

Date job started


EndDate

mm/dd/yyyy hh:mm:ss AM/PM

Date job closed

Error

Type

Varies

English description of the error type. See "Errors" below.


TypeCode

1, 2, 3, 4

Unique error type code. See "Errors" below.


Desc

Varies

English description of error. See "Errors" below.


DescCode

Varies

Unique code for the error. See "Errors" below.

Errors

Anything that happens during a run of DOTS NCOA Live 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: 

Error

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

There are four error types described below. 

Error Types


Type

TypeCode

Billable

Standard for all Gen2 Web Services

Authorization

1

No

Yes

User Input

2

No

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

Description

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 inputs.  DOTS NCOA Live requires all three inputs to be present in order for a proper validation to take place.

DescCode

Description

1

You must input a license key in the LicenseKey field.

2

You must input a job number.

3

You must input an address.

4

You must input either a Zip code or City, State.

5

Invalid format for JobId. Must be alphanumeric with no spaces and excluding special characters.

6You must input a Name.


Error type 3: Service Objects Fatal


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

DescCode

Description

1

Unhandled error.  Please contact Service Objects.


Error type 4: Domain Specific


Domain specific errors represent the errors specific to the DOTS NCOA Live service.

DescCode

Description


1

Job not found for this License Key.

The job does not exist. Please try again with a different job id. *

2

Job has been closed.

The job can no longer be used. Please try again with a new job id. *

3

First transaction of a job must contain 100 records or more.

Please try again with at least 100 unique and valid addresses. *

4

Issue connecting to NCOA engine.

Please try again. If the issue persists then please contact technical support. *

5

Street not found

Indicates that the street name was not found for the general area (city/state or zip).

6

Address not found

Indicates that a reliable address candidate was not found. Portions of the address may be incorrect or it may be too ambiguous to return a reliable candidate.

7

Street number or box number out of range

The address is invalid. The street and area appear to be correct but the number is wrong.

8

Multiple addresses match.

Indicates that multiple candidates were found that are equally likely given the input.

9

Insufficient address data

Indicates that a reliable address candidate was not found. Portions of the address may be missing or incorrect.

10

DPV Lockout. Contact Service Objects immediately.

Returned for a specific type of address case known as a false positive.

11

Request cannot contain more than 500 addresses.

Please try again with no more than 500 addresses in a single request. *

12

License Key is not linked to a valid PAF Id.

Please contact Service Objects and complete a USPS NCOA Processing Acknowledgement Form (PAF) to register your license key with the service. *

13

Performing weekly NCOA data update. Please try again in a few minutes with a new Job Id.

USPS releases new NCOALink data every week and requires that we use the newest data, so we must close all jobs using the older dataset. *
14Expired PAF agreement. Please contact Service Objects.Your USPS NCOA Processing Acknowledgement Form (PAF) has expired. Please contact Service Objects to renew and continue using the service. *
15Unable to create new NCOA Job. Please try again. If the problem persists then please contact Service Objects.There was a problem creating the new job. Please contact Service Objects and notify technical support of the error. *
16A report cannot be returned because the job is still closing. Please try again at a later time. If the issue persists then please contact Service Objects.NCOA Jobs must be closed internally before a report can be generated and jobs take several seconds to close, sometimes more than 10 seconds. If the error persists after waiting for more than a minute then please contact Service Objects. *
17There was a problem creating the report. Please contact Service Objects.Summary reports must be generated before the end of the week that they were created in. *

* This is not a billable error and it will not incur a transaction on the license key.

Integration

Integrating NCOA Live into your application is relatively simple, but has a few pitfalls to be aware of. If you are using a common platform, Service Objects may already have sample code built that you can use:

https://www.serviceobjects.com/support/dots_example_code.asp

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.

Frequently Asked Questions

How do I sign up to use DOTS NCOA Live?

First, you must fill out a "Processing Acknowledgement Form" (PAF). This form is required by the USPS for consumers of the NCOA data.

To obtain this form, please contact sales@serviceobjects.com

Once completed, we will register you and provide a license key for use with the service.

Can a Service Objects employee fill out the PAF for me?

No, all PAFs must be filled out directly by the entity requesting the service.

What can I use the NCOA data for?

The NCOA data can be used for mailing purposes only. You may not use the data for purposes of contact validation, data collection, or anything that does not involve sending mail to the contact. 

What is the "JobID"?

The JobId is how you specify which open "Job" of yours that we should apply your address transaction against. A "Job" is a kind of "open batch". As opposed to a standard batch (which goes through all records and then stops), a "Job" is a persistent batch that accepts addresses on-the-fly until the Job is closed.

Every transaction you send must be associated with a Job you've created. You create a Job by sending 100 addresses all at once to a brand new JobId of your choosing. You can make the JobId any string you like as long as you've never used it before, it has less than 50 characters, and it does not contain special characters.

Once this Job is created, it will remain open until Sunday, 11:55 pm when all client Jobs will be closed and new ones will need to be created. During this time you may run single NCOA transactions.

Why do I need to create a Job?

The USPS requires that any NCOA transactions be done as a batch of at least 100 records. Having "Jobs", although a little awkward, is the only way we can ensure that at least 100 records are processed without having to "police" our customers.

In addition, having Jobs is helpful if you're running separate lists throughout the week that should be reported separately. For example, you may have 3 separate departments in your company that each run their own mailings. They can create their own Jobs and get reporting separately for each.

Why do Jobs close every week?

The USPS releases new NCOALink data every week. It is required that we utilize the newest data within a few days of receipt. So, every week, we close the jobs that are running against the older data, update the data, and start fresh. Closing the jobs ensures that you are using the latest NCOA data.

The service is saying it found a Change of Address ("COA") match, but no address was returned. Why?

There are several reasons, but simply put it means that the USPS has knowledge that a person has moved to a new address, but does not know what that address is. It could be a data entry error, or perhaps the resident did not wish to have his or her forwarding address known.

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/nl/NCOA Live.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.

NCOALink says it can't find my street!

DOTS NCOALink doesn't know about every address, especially empty lots or new streets.  Often, it won't be able to validate these locations.  In general, we are as good as the USPS at identifying addresses. If they have an address we don't, we will have it within a month, perhaps less.

Does NCOALink do Delivery Point Validation (DPV)?  I need to know if the USPS can deliver to this address.

Yes, but at this time we don't provide as much DPV information as our DOTS Address Validation – US product. In short, if you get a "2" or a "3" in the

Diagnostics->StatusCode output field it means that your input address could not be DPV confirmed. A code of 4-8 means the input was DPV confirmed.

Is NCOA Live CASS-certified?  Can I use it to get postal discounts?

Yes and No, our core address validation engine is CASS certified.  It meets and exceeds all requirements for address correction except bulk mail discounts. AV does not print the UPSP forms required for bulk mail discounts, because of this it is not formally CASS certified.  You cannot us AV for bulk-rate postal discounts.

What are the possible errors that AV will return if an address is invalid?

Please refer to "Error Codes", above.

How can I avoid common address errors like, "Street not found", "Address not found", and "Street number or box number out of range"?

The NCOA Live service is not an address validation service. In order to get the best possible results and avoid these type of errors then please only submit valid USPS standardized addresses.

For example, a common mistake is to use the Address2 field for apartment or suite numbers. Moving secondary address data, such as "Apt 4" and "Unit B", to Address1 is required by USPS. Address2 should be reserved for extraneous information such as "C/O John Smith" or "Leave package around back". This extraneous information, however, is not helpful in finding a change-of-address (COA) candidate, and it can commonly lead to one of the above address errors.

It is highly recommended to use an address validation service that properly standardizes addresses before submitting requests to the NCOA Live service. If you do use a properly standardized address then you will find that you should not submit an Address2 value because it is not necessary.

What does "Multiple Addresses Match" mean?  How do I get a single result?

"Multiple Addresses Match" means that NCOA Live found the input 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.

Unfortunately, NCOA Live has no way of displaying the multiple ambiguous results. If this information is very important for your needs, our DOTS Address Validation – US service does provide a "GetPossibleMatches" operation to see the results, but it will require a subscription to that service.

I need to know exactly how long each of the output fields could be.  What is your standard field length?

Please email us at support@serviceobjects.com, and we'll send you the exact field length specifications.  As a general rule, you won't get a field longer than 80 characters.

Where do you get your address information?

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

How often do you update your address data?

NCOA Live updates its data every week. There are also larger updates every month.

What's the oldest change of address record I can process through NCOA?

Our system will be able to recognize any Change of Address notifications that happen within 18 months.

Conclusion

Service Objects is proud to offer you a free trial of DOTS NCOA Live. 



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

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