If you want to use our National Change-of-Address web service, DOTS NCOA Live, for contact address validation but are hesitant to dive in due to the complex nature of the service; this article is meant to set your worries aside. This blog will serve as a comprehensive guide to getting the most out of your NCOA Live subscription while addressing common questions, pitfalls, and recommended workflows. Additional information can also be found in our NCOA Live developer guide. With NCOA Live, businesses can easily update address information to maintain accurate and up-to-date contact records by accessing the USPS dataset of mail forwarding notifications.
Filling Out the Processing Acknowledgement Form
Before you can begin using NCOA Live, the USPS requires you to complete their simple Processing Acknowledgement Form (PAF) to access change-of-address data. Most of the fields in this form will be straightforward. You can look up your North American Industry Classification System (NAICS) code and business address here. To ensure correct PAF filing, we recommend using the USPS lookup tool to confirm your address and some of the additional details that the PAF requires. Please see the image below for reference.
Ensuring that your address has a ZIP+4 and a DPV Confirmation Indicator of “Y” will prevent any issues in the filing process.
Getting Your License Key and Service Endpoints
After successful filing the PAF, we will provide a license key and the service endpoint. These items will enable requests to the NCOA Live web service to check for change-of-addresses. Due to the flexible nature of our services, NCOA Live is accessible from almost any tool or programming language that can make a web service call. Specific coding examples for the service can be found in our developer guide’s sample code section.
We have sample code in most of the popular programming languages, including PHP, JAVA, Ruby, Python, ColdFusion, and C#, just to name a few. We can also provide customized code if needed and our Application Engineering team would be happy to answer any questions you may have about integrations and programming language-specific concerns.
Handling JobID Creation
Arguably the most challenging aspect of the NCOA Live web service is the USPS requirement that submissions for change-of-address lookups include an open JobID. The JobID links to your account and keeps track of the transactions you run. Each new JobID remains valid for one week, expiring at 11:50 pm Sunday evening. Opening a new JobID requires the following:
- Building an array of 100-500 addresses (100 minimum to create a job)
- Creating a personalized JobID (alpha-numeric string of fewer than 50 characters)
- Submitting the addresses, JobID, and license key to the “RunNCOA Live” operation
After submitting the initial 100-500 records for the current week’s JobID, anywhere from 1-500 records can be processed per batch. Every transaction run during that week will operate under this new JobID. At the end of the week, the JobID closes, and we update the internal change-of-address data that powers our service. The following week, another NCOA Live operation can be initiated with a new JobID following the steps listed above.
Checking for Errors and Parsing the Response
The first step to safely parsing the response is to check for any root level errors. Root level errors are largely uncommon and generally related to issues with the service or license key. If root errors appear, please don’t hesitate to contact Service Objects and we will work with you to resolve them. If there are no root level errors, you can start working with the valid response data.
The NCOA Live response returns a result with multiple nested fields. See table below for the response fields and a brief description.
RunNCOA Live 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 | 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. |
The response data comes back as a list of results corresponding to the addresses submitted. If specific address errors are detected at this level, they fall under our Domain Specific errors and apply to individual addresses. Reading the error’s description provides insight into why the service was not able to validate or return change-of-address information. Detailed notes about the individual error codes are available in the developer guide and can be seen in the table below.
Error Type 4: Domain Specific
| 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 | nsufficient 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. * |
| 14 | Expired 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. * |
| 15 | Unable 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. * |
* This is not a billable error and it will not count as a transaction against the license key.
The flexible framework of NCOA Live’s outputs allows you to integrate the results into your application to best meet your needs. We recommend exploring the various outputs such as the RawInputAddress, CASSInputAddress, and likely the most relevant information, the NCOAMatch. Because it delivers new address information in real-time, the NCOA Live service can be easily integrated into existing workflows and databases.
Maintain Better Mailing Lists with Easy Contact Address Validation
The USPS National Change-of-Address database provides a valuable resource for organizations who depend on up-to-date contact data. NCOA Live leverages the USPS dataset of forwarding notifications with a flexible API interface to provide you with the latest address information for clients and prospects. More details on all the elements of our NCOA Live service are available in our developer guide. And we are always here to help you with any questions or integration challenges you may encounter. Don’t hesitate to reach out to us today!
