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.
Many of the API methods are asynchronous because they may start a long running process. For example, it may be a few days after calling the REQUEST method
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 method so you can get the status of all the taxpayers you have submitted in the given timeframe.
The normal flow for organizations using the API is to call the VERIFY method to confirm that the taxpayer's information is true and accurate and then call REQUEST, to have TaxStatus collect consent. If
to collect the taxpayer's authorization in your flow, we offer an inflow solution (see Consent below). 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. To update the taxpayers data to the most recent/current time,
call the UPDATE 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 show your customer this 'IRS approved language' for them to accept. At the time of acceptance, you will need to
collect the IP addrss of the customer, their user agent, date and time stamp of when they checked the checkbox, and the URL where they viewed the consent languaage.
If you choose to host the consent process, you will need to have an iFrame from TaxStatus to show the IRS approved language to the taxpayer and have them agree,
to be compliant with the IRS. You can view a sample consent language here. to get an idea of what it looks like.
Since this language can change from time to time, TaxStatus will maintain the text and host it so your iFrame can retrieve it. 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 gather the necessary info from the taxpayer (name, address, TIN, etc.)
- You then Add the euid in the header, add the Company Id in the body, and POST this information from your server to the TaxStatus URL you will be given.
- The response will be a unique URL that you will call from an iFrame or you can redirect to it.
Note: The URL in the response will be unique on each successful request, with the data tied to that request. Please do not POST the same data twice.
- Taxpayer will then see the consent walkthrough, which will have all the values filled out from the form POST above. They can verify and update anything they wish.
- Once taxpayer completes the walkthrough, the iFrame or browser will redirect to the success field provied in first step (back to your flow)
For more information on this flow you need to login.
If you are getting consent from a business you will need to get the official title of the taxpayer signing for the business. Here a list of the IRS accepted
titles based on the company type or forms they file (Title is on the right side of the dash):
- Form 1065 - Partner
- Form 1065 - Limited Partner
- Form 990 - Director
- Corp/S-Corp/LLC - Chief Accounting Officer
- Corp/S-Corp/LLC - Chief Executive Officer
- Corp/S-Corp/LLC - Chief Operations Officer
- Corp/S-Corp/LLC - Chief Financial Officer
- Corp/S-Corp/LLC - President
- Corp/S-Corp/LLC - Vice President
- Corp/S-Corp/LLC - Treasurer
- Corp/S-Corp/LLC - Assistant Treasurer
- Corp/S-Corp/LLC - 1% Shareholder
- Corp/S-Corp/LLC - Shareholder
- Corp/S-Corp/LLC - Controller
- Corp/S-Corp/LLC - Managing Member
- Sole Proprietor - Owner
- Sole Proprietor - Sole Proprietor
- Trust - Executor
- Trust - Beneficiary
- Trust - Trustee
- Trust - Administrator
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.
Finally, if you don't wish to have an iFrame or you don't want to jump through the hoops above, check out the Request method. The Request
method allows you to have TaxStatus gather consent from the taxpayer. Click here for more information.