NCOA – RunNCOALive – Recommended Operation

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[]	The addresses to be validated.
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/change-of-address/

NCOAAddress

Name	Type	Values	Description
Name	String	Varies	Name of address resident.
Address	String	Varies	The primary address line.
Address2	String	Varies	The secondary address.
City	String	Varies	City name.
State	String	Varies	State abbreviation.
Zip	String	Varies	Zip code.

RunNCOALive Outputs

Name	Type	Values	Description
NameIn	String	Varies	The raw input name.
RawInputAddress	RawInputAddress[]	Varies	The list of raw input addresses.
CASSInputAddress	CASSInputAddress[]	Varies	The list of standardized addresses.
NCOAMatch	NCOAMatch[]	Varies	The list of change of address information.
Diagnostics	Diagnostics[]	Varies	Diagnostics Data
Error	Error	Varies	Error object indicating why the service could not return a result. See “Errors” page.
JobId ^[1]	String	Varies	The JobId sent to the service.

RawInputAddress

Name	Type	Values	Description
Address	String	Varies	The raw input address line
Address2	String	Varies	The raw input address2 line
City	String	Varies	The raw input city
State	String	Varies	The raw input state
Zip	String	Varies	The raw input Zip code

CASSInputAddress

Name	Type	Values	Description
Address	String	Varies	The standardized address line
Address2	String	Varies	The standardized secondary
City	String	Varies	The standardized city name
State	String	Varies	The standardized state
Zip	String	Varies	The standardized Zip+4
USPSFootnotes	String	Varies	A concatenated string of relevant 2-digit USPS “Footnote” codes that give additional information about the input address.

NCOAMatch

Name

Type

Values

Description

NameMatch

String

Varies

The name that matched the COA record.

Address

String

Varies

The primary address line that the resident moved
to.

Address2

String

Varies

The secondary address line.

City

String

Varies

The city name.

State

String

Varies

The state abbreviation.

Zip

String

Varies

The Zip+4.

CarrierRoute

String

Varies

The Carrier Route code for the COA address.

BarcodeDigits

String

Varies

The post office delivery barcode digits.

Barcode Example: 931011445011

931011445	01	1
Zip+4	Deliver Point code	Checksum Digit

COAFound

String

“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

String

Varies

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

NCOAReturnCodeDesc

String

Varies

Short English description of the COA information.

ExtendedNCOAReturnCode

String

Varies

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

Diagnostics

Name	Type	Values	Description
DiscountCode	String	1-4	A code representing discount level.
DiscountDescription	String	Varies	An English description of the discount level.
StatusCode	String	2-8	A code representing the level of quality of the input address post-validation. Higher is better.
StatusDescription	String	Varies	An English description of the level of quality of the input address post-validation.
ServiceFlags	String	Varies	USPS Service Flags output explains what additional address services were run such as RDI, eLOT, etc

References

1.^ NCOA Live Best Practices

2. NCOA Live FAQ: Your Change of Address Questions Answered