{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"01caaa45-98bc-45a0-98ee-9abd95b67c1b","name":"TrueNCOA API V2","description":"The API (Application Programming Interface) is free for developers to write code to integrate the TrueNCOA product into their product. If you're a CRM, content provider, mail shop, or service bureau, you can use the API to improve your products for your customers.\n\n---\n\n**Need your NCOA report right now?** Visit this page ([truencoa.com/getting-started](https://truencoa.com/getting-started/)) to see how to get started immediately. You'll be done in minutes, and it won't cost you a dime to find out if you need to purchase the updates.\n\n---\n\nTrueNCOA's API V2 release is an update to the API endpoint. In version 1, the API endpoint was to\n\n[https://app.testing.truencoa.com/api](https://app.testing.truencoa.com/api) and [https://app.truencoa.com/api](https://app.truencoa.com/api) , repsectively.\n\nThe API V2 endpoint removes the '/api' and updates 'app.truencoa.com' to 'api.truencoa.com'. See API Endpoint below.\n\n# Get an Account\n\nTo start using the API, you need to have an active account. Register your account in our testing environment to get started immediately - [https://app.testing.truencoa.com/users/register](https://app.testing.truencoa.com/users/register) or simply use your existing [https://app.truencoa.com](https://app.truencoa.com) login.\n\n# API Endpoint\n\nThe TrueNCOA API endpoint for the testing site is located at [https://api.testing.truencoa.com](https://api.testing.truencoa.com).\n\nThe TrueNCOA API endpoint for the production site is located at [https://api.truencoa.com](https://api.truencoa.com).\n\n# Authentication\n\nYou need to put your username/password in Headers or in the query string to authenticate yourself with every request you make.\n\n<table><tbody><tr><td><div><b>APP credentials</b></div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div><b>Descriptions</b></div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>user_name</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Your username/email address</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr><tr><td><div>password</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td><td><div>Your password</div><div contenteditable=\"false\"><div><div><div></div></div></div><div></div></div></td></tr></tbody></table>\n\n# Purchase Credits\n\nTo download your file on [app.truencoa.com](https://app.truencoa.com), you must first purchase credits. TrueNCOA uses a credit system to purchase downloads. In this system, per file pricing is $20 (1 credit) per 2 million records per file.\n\n**(Effective 5/1/2023, pricing will change to $20 (1 credit) per 2 million records per file.)**\n\nPurchasing credits is quick and easy. Users can add credits whenever they want and will only be prompted to purchase a credit after they attempt to download a file when their account has zero credits available.\n\nUsers can set up and save a default credit card within the app. When you purchase credits, you will now see a Save Card checkbox. Check this box, if you would like to save this credit card to your TrueNCOA account and purchase your credits. Next, navigate to your User page by clicking the User Icon located next to the Credit Counter.\n\nOn this page, you will see your saved credit card. Check the Default box for the credit card you would like to use for automatic purchasing via API. You will see a confirmation when you have successfully updated your payment preferences.\n\nIf you set up Default Credit Card purchasing, your credit card will be charged during the Download Data call.  \nYour credit card will be charged $20, and you will receive 1 credit. This credit will then be automatically used to download your current file. You will receive a receipt via email.\n\nRemember, you do not have to set up a Default Credit Card. You can always purchase bulk credits in app.truencoa.com or by contacting [support@truencoa.com](https://support@truencoa.com)..\n\n## Test Credits\n\nTo download your file in the testing environment, you must have at least one (1) credit in your account to download your file. You can purchase a credit by using a test credit card:\n\n<p><b>Card #</b> 4242 4242 4242 4242<br><b>Expiration Date</b>: Must be a future date - MM/YY<br><b>CVC</b>: 123</p>\n\nPurchasing a credit allows you to download your test file and to review your results. We require you to use test credits, so that when you switch to production, it will be as seamless as possible.\n\n# Before you Begin\n\nWe have a fully supported sandbox environment at [https://app.testing.truencoa.com](https://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 to the UI while you are testing your application.\n\nThere are a few different ways to start your TrueNCOA processing.\n\n#1 POST Create File: This call is a good place to start if you are processing files for your own clients. Starting here allows you to create files and caption those files with a different name. See the _POST Id - Create File_ request for more information.\n\n#2. POST Upload Data - Single Record: This call is a good place to start if you want to just test a few records at a time. This allows you to test the whole system within a few minutes.\n\n#3. POST Upload Data - Bulk: This call is a good place to start if you want to test real data and see real results. We have included a file with 150 real records that will return moves and help you understand how they are returned.\n\n# Webhooks\n\nTrueNCOA allows the use of webhooks during processing. There are two different uses for webhooks:\n\n- Notify when a file's status has changed\n    \n\nIncluding a webhook url when you post data will allow our API to send a notification to your API when your data has finished processing. This prevents you from having to continually poll the API. When you include the webhook url, this call's response will include the webhook url, and it will be listed on the file display page in the UI.\n\nTo include a webhook in your processing, you’ll need to include an additional parameter: url={{webhookurl}}. This parameter can be added when you are creating the file or when you are adding records to your file.\n\nThis parameter will contain a URL that is used for the call back. This URL should contain authentication details such as the following:\n\n- Basic: basic={username}:{password}\n    \n- Key: apikey=123456789\n    \n- Header:name\\[0\\]=name&value\\[0\\]=value\n    \n\nHere are examples of what the webhookurl will look like when using different auth details:\n\n- Basic: [https://postb.in/1576158080815-1415604364592?basic=username:password](https://desktop.postman.com/?desktopVersion=10.13.0&userId=2009332&teamId=120179)\n    \n- Key: [https://postb.in/1576158080815-1415604364592?key={keyvalue}](https://desktop.postman.com/?desktopVersion=10.13.0&userId=2009332&teamId=120179)\n    \n- Header: [https://postb.in/1576157795807-4830342447385?name[0]=testname&amp;value[0]=testvalue](https://desktop.postman.com/?desktopVersion=10.13.0&userId=2009332&teamId=120179)\n    \n\nFor testing purposes, TrueNCOA uses the following site to mock a webhook: [https://www.toptal.com/developers/postbin/](https://desktop.postman.com/?desktopVersion=10.13.0&userId=2009332&teamId=120179)\n\n1. Click \"Create Bin\"\n    \n2. Copy the URL from the part where it says \"curl -H 'X-Status: Awesome' [https://www.toptal.com/developers/postbin/1683056092792-3771018895786\".](https://desktop.postman.com/?desktopVersion=10.13.0&userId=2009332&teamId=120179) You will want just the \" [https://www.toptal.com/developers/postbin/1683056092792-3771018895786\"](https://desktop.postman.com/?desktopVersion=10.13.0&userId=2009332&teamId=120179) portion.\n    \n3. Paste this into the parameter value for \"webhookurl\".\n    \n\nYou can use this page to review the results.\n\n# TrueNCOA File Updates\n\n(Effective 5/1/2023, TrueNCOA will be sunsetting the free update feature for any client that does not have a 501(c)(3) status. If you are interested in having updates included in an annual contract, please contact us at [support@truencoa.com](https://support@truencoa.com))\n\nTrueNCOA allows you to re-process your active file(s) every week. Active files are those that were first processed within the last 95 days. This complimentary service helps you get as many standardized and updated addresses as possible.\n\nWe now provide steps for you to download your update files via the API. Continue reading to learn more.\n\nTo process updates via the API, the first step is to make sure your updates are enabled on your import file. You'll want to use the following request:\n\nPOST: Id - Create File with Updates Enabled & Webhook\n\nThis request simply includes additional keys within the BODY of the POST. The additional keys are _processupdates_ and _url_.  \nTo enable updates, set the processupdates key value to true. If you are interested in using a webhook to be notified via API that an update was processed on your file, then set the url key value to your webhook url. If you do not want to use a webhook, simply exclude the _url_ key from your request.\n\nProcess your file as you normally would. TrueNCOA will allows you to process updates on this file once a week. If you have the webhook set up, then, we will send a notification via webhook when an update was processed.\n\nYou'll be able to download these updates for free for the first 95 days. If you want to continue downloading updates for the next 95 days, you'll have to use another credit.\n\nTo download the update for free, your import file does have to be purchased and downloaded first.\n\nTo download the Update file:\n\n<ol><li><div>Follow instructions in <i>GET All Files</i>. This section will list all files that are on your account. Find the file you would like to download updates for. You'll need to retain the Id which is returned in the response.</div></li><li><div>You will use that file id to find any additional files that are related to it, such as an export or an update.</div></li><li><div>Follow the instructions in <i>GET File Files</i>. This section will list all files that are related to the file id you used in the request. Find the id for the update file you would like to download.</div></li><li><div>Next, use the update file id to create an export of the update. This can be done by replacing the {{Id}} in the <i>PATCH Create Export</i> request with the update file id you grabbed in the prior step.</div></li><li><div>Then, confirm that the export has completed. You should look for the 'Exported' status when you run the <i>GET Check Export Status</i> request. Once you have a status of Exported, you can download the data.</div></li><li><div>The final step is to download the update file data. Run the <i>GET Download Data request.</i></div></li></ol>\n\nIf you sign an annual contract with us, our team can provide you with an API call to initiate an update on your own schedule.\n\nIf you have any questions, please do not hesitate to contact us!\n\n# Start Testing!","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"2009332","team":120179,"collectionId":"01caaa45-98bc-45a0-98ee-9abd95b67c1b","publishedId":"UUxzA7SU","public":true,"publicUrl":"https://documenter-api.postman.tech/view/2009332/UUxzA7SU","privateUrl":"https://go.postman.co/documentation/2009332-01caaa45-98bc-45a0-98ee-9abd95b67c1b","customColor":{"top-bar":"FFFFFF","right-sidebar":"3070AA","highlight":"EF5B25"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.11.4","publishDate":"2021-09-27T18:12:17.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[{"name":"api.testing.truencoa.com","id":"6411cb48-a360-413d-9039-67032db70e12","owner":"2009332","values":[{"key":"domain","value":"https://api.testing.truencoa.com","enabled":true},{"key":"api_file_name","value":"","enabled":true},{"key":"id","value":"","enabled":false},{"key":"export_id","value":"1C6F33BC-575F-41E5-A48B-5D8D3AF54961","enabled":true},{"key":"id","value":"","enabled":true,"type":"any"},{"key":"webhook_url","value":"https://invalidwebhookurl.com","enabled":true,"type":"default"}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/1892ddfa2041da5f1d15d47c6bf152a06060e3aea038c52e0c3b4f83c0a178e7","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"api.testing.truencoa.com","value":"2009332-6411cb48-a360-413d-9039-67032db70e12"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/UUxzA7SU"}