Source Link: https://help.lob.com/developer-docs/use-case-guides/ncoa-responses
# NCOA responses {% hint style="info" %} 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. {% endhint %} ## 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](https://docs.lob.com/#section/API-Keys). ## 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. {% tabs %} {% tab title="TypeScript" %} ```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(); ``` {% endtab %} {% tab title="Python" %} ```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") ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="PHP" %} ```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'); } ``` {% endtab %} {% tab title="Java" %} ```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 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 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); } } } ``` {% endtab %} {% endtabs %} ## 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](../../print-and-mail/reaching-your-audience/all-about-addresses) * [Add on: Lob NCOA feature](../../print-and-mail/reaching-your-audience/additional-lob-ncoa-functionality) * [NCOALink](https://postalpro.usps.com/mailing-and-shipping-services/NCOALink)
# NCOA responses {% hint style="info" %} 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. {% endhint %} ## 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](https://docs.lob.com/#section/API-Keys). ## 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. {% tabs %} {% tab title="TypeScript" %} ```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(); ``` {% endtab %} {% tab title="Python" %} ```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") ``` {% endtab %} {% tab title="Ruby" %} ```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 ``` {% endtab %} {% tab title="PHP" %} ```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'); } ``` {% endtab %} {% tab title="Java" %} ```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 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 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); } } } ``` {% endtab %} {% endtabs %} ## 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](../../print-and-mail/reaching-your-audience/all-about-addresses) * [Add on: Lob NCOA feature](../../print-and-mail/reaching-your-audience/additional-lob-ncoa-functionality) * [NCOALink](https://postalpro.usps.com/mailing-and-shipping-services/NCOALink)