Getting Started with the API

  1. Get an account. Register your account in our testing environment to get started immediately - http://app.testing.truencoa.com/users/register or simply use your existing app.truencoa.com login.  We recommend using a separate API account to ensure it cannot be locked out accidentally, you can request this from support - support@truencoa.com
  2. Code it up. View our samples, download the source to our working command-line interface (CLI) or use the sample code below.  We support all languages, if you don't see yours listed here, contact support@truencoa.com.
  3. POST input data.  We have a fully supported sandbox environment at http://app.testing.truencoa.com which is free for you to work with so you don't waste credits.  You can see your files being processed in real time by logging in while you are testing your application.
  4. GET records.  Once the data has been processed, you can get your TrueNCOA Summary Report and output right away.  We support a number of output formats to make it easier to work with the data (CSV/JSON), and all fields are described below.

All live/production endpoints use HTTPS (SSL), all sandbox/testing endpoints use HTTP (no SSL).  Be sure you have an option to switch protocols when going live with your application if you are migrating from the sandbox/test environment to live/production.

The TrueNCOA API operates according to the same exact process users interact with when using the web-based interface.

  1. Upload your data - submit your data, create your file on the fly, then add as many records at once or one at a time
  2. Submit your file for processing - once you've added all the records you want, submit your file and wait for it to complete - you'll get two emails, one with the completion notification and another with the TrueNCOA Summary Report
  3. Get your NCOA records - create an export and download all of your records at once or request a page at a time

Samples

TrueNCOA Command Line Interface (CLI)

NEW:  We just launched our command line interface (CLI) and it's open source - 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:  http://truencoa.com/wp-content/uploads/2017/05/TrueNCOA-Command-Line-Interface.zip  There's a read_me.html and a batch (truencoa.bat) file in the zip file to help you through getting it up and running.  It should only take about 5 minutes.

  1. Download the file from:  http://truencoa.com/wp-content/uploads/2017/05/TrueNCOA-Command-Line-Interface.zip
  2. Extract the contents - you should end up with a folder like [download destination]\TrueNCOA-Command-Line-Interface\TrueNCOA Command Line Interface
  3. Customize the batch (truencoa.bat) file - see instructions below - please read the read_me.html file!
  4. Right-click on the truencoa.bat file and click Open, or;
    1. run from a command prompt
      1. Hit the Windows button, type "CMD" (without the quotes) and hit [Enter]
      2. change (CD) your working directory to where you downloaded the file
      3. Type "truencoa.bat" (without the quotes) and hit [Enter]

Customizing truencoa.bat

After downloading and extracting the contents, you will have to customize the truencoa.bat file to include the command line arguments - so you don't have to type them each time.  The read_me.html file in the extracted contents contains all of the details, but basically:

  • input file - you need to include the full path to your input file - this has to be a TAB-delimited CSV file with the correct field names, again - see the read_me.html file for details
  • user name - your login user name for the environment you are processing the file in
  • password - your login password for the environment you are processing the file in
  • url - the environment you are processing the file in - either https://app.truencoa.com/api or http://app.testing.truencoa.com/api (for testing)
  • download - true or false depending if you want the application to automatically download your data once it's done (and charge your account)

Code Samples

All samples are written around our basic REST protocol and the endpoint:  http://app.testing.truencoa.com/api/files (sandbox), and cover the basics - this is not rocket science 🙂

 

Authentication

You need to put your username/password or API id/key in headers or in the query string to authenticate yourself with every request you make.

Headers
API credentials (sent from support)
api_id API Id you receive from support, this will be in the format of a UUID
api_key API key you receive from support, this will also be in the format of a UUID
APP credentials (your existing app.truencoa.com login information)
user_name Your app.truencoa.com user name/email address
password Your app.truencoa.com password
Query String
  • API credentials - add "&api_id=[API Id you receive from support]&api_key=[API key you receive from support]
  • APP credentials - add "&user_name=[Your app.truencoa.com user name/email address]&password=[Your app.truencoa.com password]

Upload Data

You POST the data to the file endpoint:  http://app.testing.truencoa.com/api/files/[file_name]/records.  That means no special characters in the [file_name] so the query string will be accepted.

A new file will automatically be created using the parameter name [file_name] if a file with that name doesn't already exist.  If a file exists with the same name that hasn't been processed, any records being posted will be appended to that file.  You can call the POST method as many times as you'd like, and you can send in as many as 10k records at once by simply repeating the body variables.

We're expecting to see this in the BODY:

Parameter Value
individual_id Your internal record id for this record (required)
individual_first_name Person's first name (required)
individual_last_name Person's last name (required)
address_id Address id (optional)
address_line_2 Address unit or second line (optional)
address_city_name Address city (required)
address_state_code State abbreviation, 2-digit only (required)
address_postal_code Postal/zip code (required)
address_country_code Country abbreviation, 2-digit only (defaults to US) (right now we only support US, but we're adding CA shortly)

NOTE:  for address_city_name, address_state, and address_postal_code - either (address_city_name and address_state) OR (address_postal_code ) is required

You can also post as many pass-through fields as you would like.

Put it all together, and it should look something like this - for a single record POST at a time.

C#
string u = "http://app.testing.truencoa.com/api/files/testfile/records";
string b = "individual_id=1234567&individual_first_name=John&individual_last_name=Smith&address_line_1=123+N+MAIN ST&address_line_2=APT+2&address_city=CHICAGO&address_state_code=IL&address_postal_code=60606&address_country_code=US";
string json = "";
using (WebClient wc = new WebClient())
{
 wc.Headers["api_id"] = "[api_id]";
 wc.Headers["api_key"] = "[api_key]";
 wc.Headers[HttpRequestHeader.ContentType] = "application/x-www-form-urlencoded";
 json = wc.UploadString(u, "POST", b);
}
Java
CloseableHttpClient httpclient = HttpClients.createDefault();
HttpPost httpPost;
HttpResponse response;
String json = "";

List<NameValuePair> nameValuePairs;
nameValuePairs = new ArrayList<NameValuePair>();
nameValuePairs.add(new BasicNameValuePair("individual_id", "1234567"));
nameValuePairs.add(new BasicNameValuePair("individual_first_name", "John"));
nameValuePairs.add(new BasicNameValuePair("individual_last_name", "Smith"));
nameValuePairs.add(new BasicNameValuePair("address_line_1", "123 N MAIN ST"));
nameValuePairs.add(new BasicNameValuePair("address_line_2", "APT 2"));
nameValuePairs.add(new BasicNameValuePair("address_city_name", "CHICAGO"));
nameValuePairs.add(new BasicNameValuePair("address_state_code", "IL"));
nameValuePairs.add(new BasicNameValuePair("address_postal_code", "60606"));
nameValuePairs.add(new BasicNameValuePair("address_country_code", "US"));

httpPost = new HttpPost("http://app.testing.truencoa.com/api/files/testfile/records");
httpPost.setEntity(new UrlEncodedFormEntity(nameValuePairs));
httpPost.addHeader("api_id" , "[api_id]");
httpPost.addHeader("api_key" , "[api_key]");

response = httpclient.execute(httpPost);
BufferedReader rd = new BufferedReader(new InputStreamReader(response.getEntity().getContent()));
String line = "";
while ((line = rd.readLine()) != null) {
 json += line;
}
PHP
$u = 'http://app.testing.truencoa.com/api/files/testfile/records/';
$b = 'individual_id=1234567&individual_first_name=John&individual_last_name=Smith&address_line_1=123+N+MAIN ST&address_line_2=APT+2&address_city_name=CHICAGO&address_state_code=IL&address_postal_code=60606&address_country_code=US';
$headers = array(
 'api_id: [api_id]', 
 'api_key: [api_key]'
);
$curl = curl_init($u);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, $b);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$result = curl_exec($curl);
curl_close($curl);
Response

The system will respond to each POST request with the following JSON:

{
"Name": "testfile",
"Status": "Created",
"Id": "d01bcf2d-27fd-42d6-ae15-edb2205e5dbc",
"RecordCount": 1
}
Bulk Records

For bulk POST, simply duplicate the entire body for each record, like:

individual_id=1234567&individual_first_name=John&individual_last_name=Smith&address_line_1=123+N+MAIN ST&address_line_2=APT+2&address_city_name=CHICAGO&address_state_code=IL&address_postal_code=60606&address_country_code=US
&individual_id=9856222&individual_first_name=Jame&individual_last_name=Smith&address_line_1=456+N+MAIN ST&address_line_2=APT+101&address_city_name=CHICAGO&address_state_code=IL&address_postal_code=60606&address_country_code=US

Submit File

Once you have all of your records uploaded (you can check the ImportRecordCount each time you POST records), you submit your file for processing by sending a PATCH request to the file endpoint with status=submit.

C#
string u = "http://app.testing.truencoa.com/api/files/testfile";
using (WebClient wc = new WebClient())
{
 wc.Headers["api_id"] = "";
 wc.Headers["api_key"] = "";
 wc.Headers[HttpRequestHeader.ContentType] = "application/x-www-form-urlencoded";
 wc.UploadString(u, "PATCH", "status=submit");
}
Java
 CloseableHttpClient httpclient = HttpClients.createDefault();
 HttpPatch httpPatch;
 HttpResponse response;
 String json = "";

 List<NameValuePair> nameValuePairs;
 nameValuePairs = new ArrayList<NameValuePair>();
 nameValuePairs.add(new BasicNameValuePair("status", "submit"));

 httpPatch = new HttpPatch("http://app.testing.truencoa.com/api/files/testfile");
 httpPatch.setEntity(new UrlEncodedFormEntity(nameValuePairs));
 httpPatch.addHeader("api_id" , "[api_id]");
 httpPatch.addHeader("api_key" , "[api_key]");

 response = httpclient.execute(httpPatch);
 BufferedReader rd = new BufferedReader(new InputStreamReader(response.getEntity().getContent()));
 String line = "";
 while ((line = rd.readLine()) != null) {
 json += line;
 }
PHP
$u = 'http://app.testing.truencoa.com/api/files/testfile/';
$headers = array(
 'api_id: [api_id]',
 'api_key: [api_key]'
);
$curl = curl_init($u);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($curl, CURLOPT_POSTFIELDS, 'status=submit');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$result = curl_exec($curl);
curl_close($curl);

Create Export

Once your file has completed, you create an export file by sending a PATCH request to the file endpoint with status=export.  This will return a new ID for the related export file.  The default export format is the same you get through the application.  See the TrueNCOA Output File Guide.

C#
string u = "http://app.testing.truencoa.com/api/files/testfile";
using (WebClient wc = new WebClient())
{
 wc.Headers["api_id"] = "";
 wc.Headers["api_key"] = "";
 wc.Headers[HttpRequestHeader.ContentType] = "application/x-www-form-urlencoded";
 string json = wc.UploadString(u, "PATCH", "status=export");
}
Java
 CloseableHttpClient httpclient = HttpClients.createDefault();
 HttpPatch httpPatch;
 HttpResponse response;
 String json = "";

 List<NameValuePair> nameValuePairs;
 nameValuePairs = new ArrayList<NameValuePair>();
 nameValuePairs.add(new BasicNameValuePair("status", "export"));

 httpPatch = new HttpPatch("http://app.testing.truencoa.com/api/files/testfile");
 httpPatch.setEntity(new UrlEncodedFormEntity(nameValuePairs));
 httpPatch.addHeader("api_id" , "[api_id]");
 httpPatch.addHeader("api_key" , "[api_key]");

 response = httpclient.execute(httpPatch);
 BufferedReader rd = new BufferedReader(new InputStreamReader(response.getEntity().getContent()));
 String line = "";
 while ((line = rd.readLine()) != null) {
 json += line;
 }
PHP
$u = 'http://app.testing.truencoa.com/api/files/testfile/';
$headers = array(
 'api_id: [api_id]',
 'api_key: [api_key]'
);
$curl = curl_init($u);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($curl, CURLOPT_POSTFIELDS, 'status=export');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$result = curl_exec($curl);
curl_close($curl);

Download Data

Before you can download the processed data, you need to check to see if the file has completed exporting.  This is a simple GET request and checking the Status.

The GET will return the following JSON:

{
"Name": "testfile",
"Status": "Exported",
"Id": "d01bcf2d-27fd-42d6-ae15-edb2205e5dbc",
"RecordCount": 1
}

Save this Id as "exportfileid" - this will be used to GET the records/data from the export file below.

C#
string u = "http://app.testing.truencoa.com/api/files/testfile";
using (WebClient wc = new WebClient())
{
 wc.Headers["api_id"] = "";
 wc.Headers["api_key"] = "";
 string json = wc.DownloadString(url + $"files/{exportfileid}/records");
}
Java
CloseableHttpClient httpclient = HttpClients.createDefault();
HttpGet httpGet;
HttpResponse response;
String json = "";

httpGet = new HttpGet("http://app.testing.truencoa.com/api/files/{exportfileid}/records");
httpGet.addHeader("api_id" , "[api_id]");
httpGet.addHeader("api_key" , "[api_key]");

response = httpclient.execute(httpGet);
BufferedReader rd = new BufferedReader(new InputStreamReader(response.getEntity().getContent()));
String line = "";
while ((line = rd.readLine()) != null) {
 json += line;
}
PHP
$u = 'http://app.testing.truencoa.com/api/files/{exportfileid}/records';
$headers = array(
 'api_id: [api_id]',
 'api_key: [api_key]'
);
$curl = curl_init($u);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$curl_response = curl_exec($curl);
curl_close($curl);
$decoded = json_decode($curl_response);
$status = $decoded->Status;

Output Record Format

You can view the full data dictionary here.

Each record will have the following fields:

[
 {
 "input_individual_id":1,
 "input_individual_first_name":"Patrick",
 "input_individual_last_name":"Smith",
 "input_address_line_1":"5050 PEACHTREE RD",
 "input_address_line_2":null,
 "input_address_city_name":"AUBURN",
 "input_address_state_code":"GA",
 "input_address_postal_code":"20011",
 "input_address_country_code":"US",
 "record_id":"9876555",
 "global_id":"3661201",
 "change_id":"1940555",
 "individual_id":"1234567",
 "household_id":"7654321",
 "first_name":"PATRICK",
 "last_name":"SMITH",
 "company_name":null,
 "street_number":"1315",
 "street_pre_direction":null,
 "street_name":"RIDGEVIEW",
 "street_post_direction":null,
 "street_suffix":"RD",
 "unit_type":null,
 "unit_number":null,
 "box_number":null,
 "city_name":"AUBURN",
 "state_code":"GA",
 "postal_code":"30011",
 "postal_code_extension":"3334",
 "carrier_route":"R055",
 "address_status":"V",
 "error_number":"A1",
 "address_type":"S",
 "delivery_point":"15",
 "check_digit":"6",
 "delivery_point_verification":"YN NN",
 "delivery_point_verification_notes":"AABB",
 "vacant":"N",
 "congressional_district_code":"10",
 "area_code":"770",
 "latitude":"34.00070",
 "longitude":"-83.8235",
 "time_zone":"EST",
 "county_name":"BARROW",
 "county_fips":"013",
 "state_fips":"13",
 "barcode":"/300113334156/",
 "lacs":null,
 "line_of_travel":"0105",
 "ascending_descending":"A",
 "move_applied":"20170202",
 "move_type":"I",
 "move_date":"201509",
 "move_distance":"25",
 "match_flag":"M",
 "nxi":"A",
 "ank":null,
 "residential_delivery_indicator":"Y",
 "record_type":"C",
 "record_source":"PN",
 "country_code":"US",
 "address_line_1":"1315 RIDGEVIEW RD",
 "address_line_2":null
 }
]