DOTS NCOA Live

• Introduction
  • Usage Overview
• Developer Guide Map
• Integration Basics

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.

• 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 alsoallows 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. a.Build an array of 100-500 addresses (100 minimum to create job)
   2. b.Create a personalized JobId (can be almost any alpha-numeric string of less than 50 characters)
   3. c.Submit the addresses, JobId, and License Key to the “RunNCOA Live” operation.
2. Run more transactions against your personalized JobId
   1. a.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. a.Calling either “GetCASSSummaryReport” or “GetNCOALinkSummaryReport” will close your job and return report statistics.
   2. b.These statistics will be available at any time for up to 3 months.
   3. c.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).

Developer Guide Map

• Operations
  • This section lists the DOTS NCOA Live operations and goes into the details behind the inputs and outputs. 
    • Operations:
    • RunNCOALive (Recommended Operation)
    • RunNCOALiveSingleAddress
    • GetCASSSummaryReport
    • GetNCOALinkSummaryReport
    • GetJobSummaryReport

• Codes, Notes, Correction
  • This section shows additional supporting data tables for the codes, notes, and corrections.

• Errors
  • This section reflects details on the error outputs that can happen with the service.

• Code Snippets and Sample Code
  • Here you’ll find code snippets for various programming languages and frameworks along with links to our sample code page on the web site.

• Frequently Asked Questions
  • This is a list of some of the questions we hear more often that you can reference and get answers on right away.

Integration Basics

• Integrating NCOA Live into your application is relatively simple, but has a few pitfalls to be aware of. If you are using a common platform, Service Objects may already have sample code built that you can use:
• https://www.serviceobjects.com/developers/sample-code/
• 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.com for more details.

• Web Service Structure:

• 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 is supported. The reporting operations support all three.

• The host path, or physical location of the web service is here:
  https://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.) :
  https://trial.serviceobjects.com/nl/NCOALive.asmx?WSDL