• 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

931011445011
Zip+4Deliver 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