NCOA restrictions
Table of Contents
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');
}
DeleteJava
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.