Introduction

The Tax Data API has been created to make it simple and easy to collect IRS tax data from your customers. We provide a standard REST-based API to provide a fast way to start using TaxStatus. With this API you can request taxpayer consent (via TaxStatus or building flow internally), view all taxpayer data (official income, levy, liens, filings, etc.), monitor the IRS for changes to accounts, and download official IRS tax transcripts. We also provide a number of report calls where data is arranged to show assets, liabilites, investments, income, etc.

Many of the API methods are asynchronous because they may start a long running process. For example, it may be a few days after the taxpayer goes through the consent process before the INDIVIDUAL or BUSINESS details are available. Usually it is same day or next day, however, it is possible for it to take longer. Therefore, we have provided the LASTSTATUS V2 method so you can get the status of all the taxpayers you have submitted in the given timeframe.

NOTE: You will notice in the documentation that we use a Client Id to represent the taxpayer and eliminate passing SSNs. In the signed callback and LASTSTATUS V2 payloads, the TIN wil be this Client Id. You can use the First Name, Laat Name and Email address as the key to your taxpayer in yoru system. then store the Client Id you received, in your system. This will be what you use for all calls. You will substitue any field called tin or ssn with the Client Id.

API Walkthrough

The normal flow for organizations using the API is TaxStatus will prrovide a link, customized for your company to give to your customers. This link will walk users through the consent process to allow TaxStatus to get consent from the IRS and can be iFramed, new tab, or emailed. This process only takes minutes and TaxStatus will handle all the processing to the IRS to get consent. If you are hosting a webhook, you will receive a callback once the taxpayer signs and then again when data is available. Otherwise, you can call the LASTSTATUS endpoint to get the status of all your customers for the last 30 days.

We also provide a way for the taxpayer to log in to the IRS and approve the consent, so data is available immediately.

Once the IRS has recorded the consent, organizations can call the INDIVIDUAL or BUSINESS methods to pull the summary of the taxpayers history. If you need the actual transcripts for the taxpayer, call the TRANSCRIPT method or to get all the fields as key value pairs, you can call the TRANSCRIPTDETAIL method.

We can help with this flow and give you options on the best ways to collect consent from the taxpayer.

We recommend you explore the API using the API Walkthrough. Once you register, and are approved, this page will provide everything you need to test our APi in our development sandbox.

Collecting Consent in Your Own Flow

Taxpayers own their own tax data. In order for you to obtain a taxpayer's tax data, they need to authorize the IRS to allow you to see their data. This is done by having the taxpayer agree to language stating who can see it and what they will do with it. During your consent process, you will need to have the taxpayer use the one-click link, porvided by TaxStatus, to navigate to our consent wizard. We will take it from there and submit all necessary information to the IRS.

If you choose to host the consent process, you will need to have an iFrame or open a new tab from TaxStatus to show the IRS approved language to the taxpayer and have them agree, to be compliant with the IRS. This text can have business rules around it so you can add language specific to your company. Here is a breif description of how it works:

  • Your onboarding flow will provide the consent link provided by TaxStatus
  • You will receive a callback to your webhook once the taxpayers finishes the wizard. Or you can call the LASTSTATUS (v2) call once or twice a day to get the status of your taxpayers.
  • Once taxpayer completes the walkthrough, the iFrame or browser can redirect to the success URL if provided to TaxStatus during company onboarding

Note: TaxStatus will work with you to make sure you are up and running quickly. You will be provided with a sub domain and all keys needed for this process.