NCOA responses

Customers must meet certain requirements to access this additional NCOA functionality. Please review the below and reach out to your Account Manager to see if you are eligible.

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 reporting 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, 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 a mail piece is created, 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(); 

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")

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

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');
}

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);
         }
     }
 }

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

• All about addresses
• Add on: Lob NCOA feature
• NCOALink