API Walkthrough

We have prepared this walkthrough to show you step-by-step how to use the API to collect taxpayer consent and download IRS data and transcripts. In the production environment, the company will need to have consent granted by the taxpayer, to the company, for all calls except REQUEST.

Once you register, are approved, and login, you will be able to see the API endpoint, Oauth keys, and your registered company Id.

Test Data

Due to the sensitive nature of tax information, we can not allow you to use real social security numbers and pull real taxpayer information. Therefore we have created some test data and mapped out example use-cases so you can create and test your applications. Use the following taxpayers when developing your application against the Test environment.

  ID Type ID Value First Name Last Name Business Name
       
  SSN 222222222 Sammy Smith
  SSN 333333333 Linda Jones
  EIN 555555555 Acme Inc

Authorization POST

TaxStatus uses OAuth2 to authenticate and authorize the API calls. For more information on OAuth2 you can check here. The choreography needs to call to authenticate and get an authorization token which will need to be included in the header of each call.

Token URL
Grant Type
Client Id
Secret
Scope

Request Body application/x-www-form-urlencoded

The client credentials will be UTF8 encoded in the body of the call. All attributes listed above are required. The following is a sample call:

POST /token HTTP/1.1 Host: <authorization-server.com> grant_type=client_credentials &client_id=xxxxxxxxxx &client_secret=xxxxxxxxxx &scope=xxxxxxxxxx

Response Body application/json

The following is a list of the fields returned in the OAuth response.

Attributes

  • access_token The access token that was issued by the authorization server. This needs to be in the header for all API calls.
  • token_type The type of token this is, will just the string “bearer”.
  • expires_in The server should reply with the duration of time the access token is granted for.

Example of a successful token response:

HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3", "token_type":"bearer", "expires_in":3600, }

Callbacks POST

In the Request and Taxpayers calls, you may use a callback to have your system informed once the taxpayer data is available. If provided, the TaxStatus system will POST a JSON object to the endpoint provided. The JSON sent will be the same as the Individual or Business calls, whichever is appropriate. For this environment, the default is Individual. Check the box if you would like to receive Business data. Note: The callback will only POST to an HTTPS endpoint. If the callback is to an HTTP endpoint the callback will redirect to HTTPS.

Please login to learn more about Callbacks.

Reports

Taxstatus offers specialized reports based on taxpayer data. You must have consent from the taxpayer to access reports. To see what we offer, you need to be authenticated.

Sample Files

TaxStatus has additional tools to help with integrating to your company. Once you register, are approved, and login, you will see these.