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/products/address-geocoding/ncoa-live


NCOAAddress

 Name

TypeValues

Description

Name

StringVaries

Name of address resident.

Address

StringVaries

The primary address line.

Address2

StringVaries

The secondary address.

City

StringVaries

City name.

State

StringVaries

State abbreviation.

Zip

StringVaries

Zip code.

RunNCOALive Outputs

Name

Type

Values

Description

NameIn

String

Varies

The raw input name.

RawInputAddress

RawInputAddress[]

VariesThe 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[]VariesDiagnostics Data

Error

Error

Varies

Error object indicating why the service could not return a result. See "Errors" page.

String

Varies

The JobId sent to the service.


RawInputAddress

 Name

TypeValues

Description

Address

StringVaries

The raw input address line

Address2

StringVaries

The raw input address2 line

City

StringVaries

The raw input city

State

StringVaries

The raw input state

Zip

StringVaries

The raw input Zip code


CASSInputAddress

 Name

TypeValues

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

NameTypeValues

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


<button class="accordion">The post office delivery barcode digits.</button>
 <div class="panel">
 <p><b>Barcode Example: 931011445011</b>
 <table>
 <thead>
 <tr class="row-1 odd">
 <th class="column-1">931011445</th><th class="column-2">01</th><th class="column-3">1</th>
 </tr>
 </thead>
 <tbody class="row-hover">
 <tr class="row-2 even">

 <td class="column-1">Zip+4</td><td 
class="column-2">Deliver Point Code </td><td 
class="column-3">Checksum Digit </td>
 </tr>
 </tbody>
 </table>
  
  
 </div>


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

TypeValues

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


NCOA Live FAQ: Your Change of Address Questions Answered

References

<style>
.accordion {
  background-color: #f7f7f7 !important;
  color: #444 !important;
  cursor: pointer !important;
  padding: 18px !important;
  border: none !important;
  width: 100%;
  text-align: left !important;
  outline: none !important;
  font-size: 15px !important;
  transition: 0.4s !important ;
}

.active, .accordion:hover {
  background-color: #efefef !important; 
}

.panel {
  padding: 0 18px  !important;
  display: none ;
  background-color: white !important;
  border: none !important;
  overflow: hidden  !important;
}


.accordion:after {
  content: '\02795'; /* Unicode character for "plus" sign (+) */
  font-size: 13px ;
  color: #777 ;
  float: right ;
  margin-left: 5px;
}

.active:after {
  content: "\2796" ; /* Unicode character for "minus" sign (-) */
}

</style>
<script>
var acc = document.getElementsByClassName("accordion");
var i;

for (i = 0; i < acc.length; i++) {
  acc[i].addEventListener("click", function() {
    this.classList.toggle("active");
    var panel = this.nextElementSibling;
    if (panel.style.display === "block") {
      panel.style.display = "none";
    } else {
      panel.style.display = "block";
    }
  });
}
</script>