National Change Of Address (NCOA) Command Line Interface (CLI)

Overview

National Change Of Address (NCOA) Command Line Interface (CLI) enables you to process files from your own computer without having to log in to the User Interface (UI) at https://app.truencoa.com - although you will need to register and add credits and assign a default credit card (if you want auto purchase to work) in order to use the CLI.  If you do not have a default credit card setup, the system will notify you that the file cannot be output when you run out of credits.  In that case, you will need to log in to the application and add more credits manually.

How It Works

Command Line Interface

You can view our CLI documentation here:  https://github.com/truencoa/cli. This was built using Visual Studio Community Edition, you can get that here for free:  https://www.visualstudio.com/

You can download the stand-alone application here:  Command Line Interface.

The CLI accepts the following arguments as: truencoa.exe filename id key [url] [download]

• filename (required) - the fully qualified path and name to the input file (CSV, tab-delimited)
• id (required) - the API id or account user name/email address
• key (required) - the API key or account password
• url (optional) - the API endpoint URL - defaults to https://api.truencoa.com/ (production) or https://api.testing.truencoa.com/ (testing)
• download (optional) - automatically download the processed file - defaults to false, no file will be downloaded, when set to true, the file will be downloaded and credits will be automatically deducted
• suppress (optional) - automatically suppress all previously exported data from the current export - NOTE: the download argument must be set when using this argument
• charge - automatically charge my saved card if there are not enough credits available - NOTE: you must have a saved card (entered in and saved throught the app). This will only charge your card for one credit at a time. You will receive an email with your receipt

Examples

• Basic processing, no download: truencoa_cli.exe "d:\myfile.txt" "[email protected]" "Password123$" "https://api.testing.truencoa.com/" false
• Advanced processing, with download: truencoa_cli.exe "d:\myfile.txt" "[email protected]" "Password123$" "https://api.testing.truencoa.com/" true

NOTE: if you're using a batch (BAT) file to automate the process and store the command-line parameters, and your password contains a percent symbol (%), you need to add an additional percent symbol to make it work.

Input File

The CLI needs the following information:

• User name & password to https://app.truencoa.com (or https://app.testing.truencoa.com for testing)
  • You can have multiple users so that you can control CLI usage via a separate account in case you need to disable it without disabling your primary user account.  To add a CLI user, email [email protected] with the email address of the user
• Local folder path where input files are stored.  The files will need to be in a specific format (CSV, tab-delimited) with the predefined column names (headers):
  • Standard Headers
    • individual_id - your unique id
    • individual_first_name - first name
    • individual_last_name - last name or business name
    • address_line_1 - address line 1 or full street address
    • address_line_2 - address line 2 or blank
    • address_city_name - city name
    • address_state_code - state code, like 'IL'
    • address_postal_code - five-digit or full postal code (please make sure leading zeroes are present)
  • Optionally, you can include the following fields:
    • individual_full_name - only one full name field, do not include individual_first_name and individual_last_name fields when including this
    • address_country_code - blank or 'US'

 

Note: Pass-throughs or additional fields not listed above are not allowed.

 

Payment

You will automatically be charged if the "download" parameter is set to true. If you do not have any credits available, the export file will not be downloaded. You can login to the app at the URL you submitted the file to in order to view your credits and to save a credit card and enable automatic credit purchases. Learn more about pricing here: https://truencoa.com/pricing.

Working in our test environment? Feel free to use our test credit card details to test purchasing your test file.

Reports

The NCOA Report and CASS Report will be written back to the input file folder automatically if the "download" parameter is set to true.

• {input file name}.export.csv.cass.pdf
• {input file name}.export.csv.ncoa.pdf