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 in order to use the CLI.  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 also 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


  • Basic processing, no download: truencoa.exe "d:\myfile.txt" "email@address.com" "Password123$" "https://api.testing.truencoa.com/" false
  • Advanced processing, with download: truencoa.exe "d:\myfile.txt" "email@address.com" "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 support@truencoa.com 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'



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.

Output File

The export file will be written back to the input file folder automatically with the same input file name with ".export.csv" added.


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