Lob Help Center

NCOA Restrictions


What is NCOA

National Change of Address (NCOA) is a service offered by the USPS, which allows individuals or businesses who have recently moved to have any mail forwarded from their previous address to their new address.

As a CASS-certified Address Verification Provider, Lob also offers NCOA functionality to our Print & Mail customers. With the Lob NCOA feature enabled, Postcards, Self-Mailers, Letters, Checks, and Addresses can automatically be corrected to reflect an individual's or business' new address in the case that they have moved (only if they have registered for NCOA with the USPS).

Prerequisites

In order to leverage Lob’s NCOA feature, we must have a signed Processing and Acknowledgement Form and the account must meet other volume requirements. If NCOA is not currently enabled for your account, please reach out to your Account Manager or your Customer Success Manager for more information and next steps.

A live API key is also required. In order to get this, please refer to step one of Getting Started.

How to use Lob’s NCOA functionality

Using the NCOA data is simple. When an address is created in the Lob API and the feature is enabled for the account, the recipient and address are used to look up current change of address records.

If there is a currently active COA, then the mail piece created will include the recipient’s new address information and the response from the Lob API will include a representation of the Address record that has a recipient_moved value of true and redacted values for address_line1 and address_line2, but all other values will reflect the COA changes.

Code example

For example, an application is sending a check. Because of the business logic of this application, when the recipient has changed addresses, we want to cancel the check instead of allowing it to be rerouted.

For this, we will assume there is a verified bank account already recorded and the application is aware of the Lob record id for that bank account.

TypeScript

import {
    Configuration,ChecksApi, CheckEditable,CountryExtended, AddressEditable 
} from "@lob/lob-typescript-sdk"; 
  
async function demo() { 
    const config: Configuration = new Configuration({ 
        username: "test_XXXXXXXX", 
    }); 
  
    const checkToCreate = new CheckEditable({ 
        description: "Reimbursement $1", 
        to: new AddressEditable({ 
            name: "HARRY ZHANG", 
            address_line1: "185 BERRY ST", 
            address_line2: "SUITE 6100", 
            address_city: "SAN FRANCISCO", 
            address_state: "CA", 
            address_zip: "94107" 
        }), 
        from: new AddressEditable({ 
            name: "LEORE AVIDAR", 
            address_line1: "210 King Street", 
            address_city: "SAN FRANCISCO", 
            address_state: "CA", 
            address_zip: "94107", 
            address_country: CountryExtended.Us, 
        }), 
        bank_account: "bank_XXXXXXXX", 
        amount: 1, 
    }); 
  
    const checksApi = new ChecksApi(config); 
    try { 
        const newCheck = await checksApi.create(checkToCreate); 
        if (newCheck.to?.recipient_moved) { 
            console.log("Recipient has moved - cancel ") 
            await checksApi.cancel(newCheck.id); 
        } 
    } catch (err) { 
        console.error(err); 
    } 

  
demo().then().catch(); 
Delete

Python

import lob
lob.api_key = "test_XXXXXXXX"
 
newCheck = lob.Check.create(
description = 'Reimbursement $1',
   to_address = {
     'name': 'Harry Zhang',
     'address_line1': '185 Berry St',
     'address_line2': '# 6100',
     'address_city': 'San Francisco',
     'address_state': 'CA',
     'address_zip': '94107'
   },
   from_address = {
     'name': 'Leore Avidar',
     'address_line1': '210 King St',
     'address_city': 'San Francisco',
     'address_state': 'CA',
     'address_zip': '94107'
   },
   bank_account = 'bank_XXXXXXXX',
   amount = 1.00,
 )
 
if('recipient_moved' in newCheck.to_address.__dict__):
lob.Check.delete(newCheck.id)
    print("Recipient has moved - cancel")
Delete

Ruby

require 'lob.rb' 
require 'pp'  
 
 @lob = Lob::Client.new(api_key: "test_XXXXXXXX") 
 
newCheck = @lob.checks.create(
description: 'Reimbursement $1',
   to: {
     name: 'Harry Zhang',
     address_line1: '185 Berry St',
     address_line2: '# 6100',
     address_city: 'San Francisco',
     address_state: 'CA',
     address_zip: '94107'
   },
   from: {
     name: 'Leore Avidar',
     address_line1: '210 King St',
     address_city: 'San Francisco',
     address_state: 'CA',
     address_zip: '94107'
   },
   bank_account: 'bank_XXXXXXXX',
   amount: 1.00
 ) 
 
if(newCheck['to']['recipient_moved'])
   @lob.checks.destroy(newCheck.id)
   pp 'Recipient has moved - cancel' 
end
Delete

PHP

$lob = new \Lob\Lob('test_XXXXXXXX');
 
$newCheck = $lob->checks()->create(array(
    'description' => 'Remimburse $1',
    'to[name]' => 'Harry Zhang',
    'to[address_line1]' => '185 Berry St',
    'to[address_line2]' => '# 6100',
    'to[address_city]' => 'San Francisco',
    'to[address_zip]' => '94107',
    'to[address_state]' => 'CA',
    'from[name]' => 'Leore Avidar',
    'from[address_line1]' => '210 King St',
    'from[address_city]' => 'San Francisco',
    'from[address_zip]' => '94107',
    'from[address_state]' => 'CA',
    'bank_account' => 'bank_XXXXXXXX',
    'amount' => 1.00
 ));
   
$prop = 'recipient_moved';
if (isset($newCheck['to']->$prop)) {
    $lob->checks()->delete($newCheck['id']);
    print_r('Recipient has moved - cancel check');
} else {
    print_r('Check is in the mail');
}
Delete


Java

import com.lob.Lob;
import com.lob.model.Address;
import com.lob.model.Check;
import com.lob.net.LobResponse;
public class App 
{
    public static void main( String[] args )
    {
        Lob.init("test_XXXXXXXX");
         try {
LobResponse<Check> response = new Check.RequestBuilder()
                 .setDescription("Remimburse $1")
                 .setAmount("1.00")
                 .setTo(
                         new Address.RequestBuilder()
                                 .setName("Harry Zhang")
                                 .setLine1("185  Berry Street")
                                 .setLine2("Ste 6100")
                                 .setCity("San Francisco")
                                 .setState("CA")
                                 .setZip("94107")
                 )
                 .setFrom(
                         new Address.RequestBuilder()
                                 .setName("Leore Avidar")
                                 .setLine1("210 King St")
                                 .setCity("San Francisco")
                                 .setState("CA")
                                 .setZip("94107")
                 )
                 .setBankAccount("bank_XXXXXXXX")
                 .create();
  
 Check newCheck = response.getResponseBody();
                 if(newCheck.getTo().getRecipientMoved() != null) {
LobResponse<Check> deleteResp = Check.delete(newCheck.getId());
System.out.println("Recipient has moved - cancel check");
                 } else {
System.out.println("Check is in the mail");  
                 }
         } catch (Exception err) {
System.out.println("Error on check creation: " + err);
         }
     }
 }
Delete


Conclusion

Lob’s NCOA feature, once enabled for an account, allows a consuming application to more completely manage the behavior of mail pieces when a recipient has moved.

Further resources

Was this article helpful?