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 and POST are supported. The reporting operations support all three.

The host path, or physical location of the web service is here:
http://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.) :
http://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
NCOA Live Java Code Snippet
NCOA Live PHP Code Snippets
NCOA Live RoR Code Snippets
NCOA Live Python Code Snippet
NCOA ColdFusion Code Snippet
NCOA VB Code Snippet
NCOA Apex Code Snippet
NCOA TSQL Code Snippet
NCOA Live Java Rest Code Snippet
NCOA Live RoR Rest Code Snippets
NCOA Live Python Rest Code Snippet
NCOA ColdFusion Rest Code Snippet
NCOA VB Rest Code Snippet
NCOA TSQL Rest Code Snippet

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#

List of Operations

RunNCOA Live – Submit 1-500 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.
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.   

RunNCOA Live

 

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.

RunNCOA Live 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
www.serviceobjects.com.

 

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

"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

1, 2, 3, 4, 5

See "Error Codes" below.

 

TypeCode

Always null

Deprecated, no longer used.

 

Desc

Varies

English description of error.

 

DescCode

Varies

Unique code for the error.

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 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 new address was not provided to the USPS - a new address cannot be provided.

03

PO BOX Closed, No Forwarding Address

Match found, but 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 rechaining - 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

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
www.serviceobjects.com.

 

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

1, 2, 3, 4, 5

See "Error Codes" below.

 

 

TypeCode

Always null

Deprecated, no longer used.

 

 

Desc

Varies

English description of error.

 

 

DescCode

Varies

Unique code for the error.

 

*This column corresponds to the different locations and sections on the 3553 form to enter the values from 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
www.serviceobjects.com.

 

GetNCOALinkSummaryReport Outputs

 

Name

Values

Description

CustomerPAFId

Varies

The PAF Id assigned to 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 type of Pre-processes performed.

ConcurrentProcessesPerformedFlag

Varies

Flag detailing type of concurrent processes performed.

PostProcessesPerformedFlag

Varies

Flag detailing 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

1, 2, 3, 4, 5

See "Error Codes" below.

Error.TypeCode

Always null

Deprecated, no longer used.

Error.Desc

Varies

English description of error.

Error.DescCode

Varies

Unique code for the error.

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

1, 2, 3, 4, 5

See "Error Codes" below.

 

TypeCode

Always null

Deprecated, no longer used.

 

Desc

Varies

English description of error

 

DescCode

Varies

Unique code for the error

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. *

* 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 pit-falls to be aware of. If you are using a common platform, Service Objects may already have sample code built that you can use:

http://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.comfor 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.

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 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:55pm 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:
http://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 inputaddress 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. 

Sign up today for a free trial at:
http://www.serviceobjects.com/products/address/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.

Labels
  • None