This public API is built using the light-weight architecture REST. Our API takes advantage of HTTP requests to post any data requests. This API encodes all requests, response bodies, and error codes in JSON.

Users are provided access to exclusive sandbox environment to test the application with live characteristics. The API uses authentication keys to validate every request received and grant further access to the API.

Through our different API endpoints, users can create, update, validate, and transmit the IRS tax returns. The API uses the concept of webhooks to instantly communicate the sender on status of tax forms. It also allows the sender to place a PDF download request through Webhooks.

The API generates an authentication key every time a request hits the application. This authentication key will be a unique identifier that allows the sender to interact with the application. When you send a request to the API, it will validate the details of the authentication key contained in the request header. Upon verifying the information, the API will generate its own authentication key, which in turn has to match with the authentication key part of the request header. Only then, the request will be processed.

The authentication key that you send in the request header should have two parts. The first part should have the public key and the second part should contain the following fields in a hashed string and should be signed by HMAC using the private key specific to your sandbox environment:

• Host Name -The URL api.taxbandits.com
• User Token - This is generated against a user account provided in the sandbox environment.
• Timestamp - Time, in UTC time format.
• IP Address - From where the request originates.
• Authentication Key - An unique identifier created at the API end using the private key.

{
  "Connection": "Keep-Alive ",
  "Expect": "100-continue ",
  "Host": "api.taxbandits.com ",
  "UserToken": "7d1928f3e7e047febb36cded6869e2f5 ",
  "Timestamp": "12/07/2018 08:43:11.802 AM ",
  "Authentication": "bfb1d4dd466dee13:qwoHVxgg2/7NAnGB92Prj7AbZcUf4U7IxBO7yw6aP9I= ",
  "IpAddress": "61.12.94.6 ", 
}

OAuth2.0 is a HTTP authentication scheme that involves security tokens called Access tokens or Json Web Tokens (JWT). Each request is authenticated with the access token.

The access token is a cryptic string, usually generated by the server in response to a request. The client must send this token in the Authorization header when making requests to protected resources.

The OAuth2.0 authentication is available on the version 1.5.0 and above. The older versions will continue to have the SWT authentication.

Here are the steps on how you can get the JWT from TaxBandits:

Step 1: Retrieve the Authentication Keys
Retrieve the below 3 keys in Console site using your credentials. Navigate to Settings >> API Credentials

• Client ID
• Client secret
• User Token

Note: Do not share the keys with any individual or business.



Step 2: Request the Access Token
To request an Access Token, you need to create a signature (JSON Web Signature) for Authentication. The JWS consists of 3 parts as given below,

• Header
• Payload
• Signature

Header:
{
"alg": "HS256",     /*Algorithm = HS256*/
"typ": "JWT"    /*Type = JSON Web Token (JWT)*/
}

Payload:
{
"iss": "968a9c78dae29a29”,     /*Issuer: Client ID retrieved from the console*/
"sub": "968a9c78dae29a29",    /*Subject: Client ID retrieved from the console*/
"aud": "a574b75f18b24fc09f9039ffb5cb08f3",    /*Audience: User Token retrieved from the console*/
"iat": 1516239022    /*Issued at: Number of seconds from Jan 1 1970 00:00:00 (Unix epoch format)*/
}

Signature:
HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
siqHfLy59g3UHxrb5gjxg    /*Client Secret retrieved from the console*/
)

Combine the Header, payload and signature to create the JWS.

Sample JWS:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOi
I5NjhhOWM3OGRhZTI5YTI5Iiwic3ViIjoiOTY4YTljNzhkYWUyOWEyOSIsImF1
ZCI6ImE1NzRiNzVmMThiMjRmYzA5ZjkwMzlmZmI1Y2IwOGYzIiwiaWF0IjoxN
TE2MjM5MDIyfQ.HNQznxlPyVt62kyUeVwtk1-uzm1uDWH4NBDLShA6Ac0

Once the JWS is created, then send a request to the Authentication Server for an Access token.

Authentication Server URL:
Sandbox: https://testauth.taxbandits.com/v1/auth
Live: https://auth.taxbandits.com/v1/auth

Once we receive a JWS from the client, TaxBandits will provide the JWT (Access token) to the client in the following format:

Header:
{
"alg": "HS256",     /*Algorithm = HS256*/
"typ": "JWT"    /*Type = JSON Web Token (JWT)*/
}

Payload:
{
"iss": "testapi.taxbandits.com”,
"sub": "968a9c78dae29a29",
"aud": "a574b75f18b24fc09f9039ffb5cb08f3",
"iat": 1516239022,
"exp": 1516239022    /*Expiry: Number of seconds from Jan 1 1970 00:00:00 for the expiry. The Access Token is valid for 60 minutes*/
}

Signature:
HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
siqHfLy59g3UHxrb5gjxg    /*Master Secret Key*/
)

Step 3: Use the Access Token to send API Requests
Once you obtain the JWT (Access token), you can determine its expiry by the “ExpiresIn” value in the Response. You will have to use the same JWT along with every API request until the token expires.

Example:

URL:https://api.taxbandits.com/v1.5.0/form1099misc/create

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3
MiOiJ0ZXN0YXBpLnRheGJhbmRpdHMuY29tIiwiYXVkI
joiYTU3NGI3NWYxOGIyNGZjMDlmOTAzOWZmYjVjYjA4ZjMiLCJp
YXQiOjE1OTU5MjAxMjQsImV4cCI6MTU5NTkyNzMyNH0.BIg8764SOhOai9As
3uRSidrF1-B9CxL6D5z4OggcVbs
Content-Type: application/json

{
"StatusCode":200,
"StatusName":"Ok",
"StatusMessage":"Successful API call",
"AccessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ0ZXN0YXBpLnRheGJhbmRpdHMuY29tIiwiYXVkIjoiYTU3NGI3NWYxOGIyNGZjMDlmOTAzOWZmYjVjYjA4ZjMiLCJpYXQiOjE1OTU5MjAxMjQsImV4cCI6MTU5NTkyNzMyNH0.BIg8764SOhOai9As3uRSidrF1-B9CxL6D5z4OggcVbs ",
"TokenType":"Bearer",
"ExpiresIn":3600,
"Errors":null
}

The API supports the following forms:

• Information Returns: W-2, Transmittal form W-3, 1099-MISC, and Summary Tax Report 1096.
• Employment Tax Forms: 940, 940 Schedule R, 941, 941 Schedule R, and 944.

Explore the event sequence below that leads to the creation of a tax form. Once you send a request to the API, its authenticity is verified through a series of validation checks before the actual creation of the form begins.

Request from the sender: The sender sends an API request to the CREATE API Endpoint so as to create a form.

Authentication of the request: The request is validated for authenticity before it is processed further.

Data Validation: Once the request is authenticated, the data across all fields are subjected to validation. The API does basic validation checks for key fields like Business Name, EIN, and SSN. If these fields pass the validation checks, the form is processed further, if not, the errors are updated through Response JSON.

Business Rule Validation: Records that clear data validation will be subjected to business validation checks. Here, the data are validated against a set of business rules. Records that fail business validation are updated through Response JSON along with the errors observed.

Process the Information: Records that clear business validation are processed further and their respective statuses are communicated in Response JSON through a collection of Success Records.

Create Form: The API will create forms for records that clear the business validation. The response to this create request will have a Submission ID and Record ID unique to a return which needs to be referenced for that particular return across all API calls.

Update Form: To update/change any information, an API request has to be sent to the UPDATE API Endpoint.

Validate Form: To validate a return for business rules, an API request has to be sent to the VALIDATE API Endpoint. Validation is generally done before transmitting the form to the IRS.

Transmit Form: When the return is ready for transmission, an API request has to be sent to the TRANSMIT API Endpoint. And then, the e-filing process is initiated.

Handling Errors in Response: In order to assist the sender to understand the error codes, the unique error codes are made available in Response JSON.

Receive the status of return using Webhooks: The API uses Webhooks to communicate the filing status to the sender. The Webhooks URL has to be configured in the Sandbox account.

Download PDF using Webhooks: An API request has to be sent to the GETPDF API Endpoint to download the PDF form. In turn, the request is processed offline, PDFs are generated and saved in a secure path. The sender is communicated on the secure location path through Webhooks.

Generate Transmittal forms using Webhooks: An API request has to be sent to the GETPDF API Endpoint to generate the transmittal forms like W-3, 1096, etc. In turn, the request is processed offline, PDFs are generated and saved in a secure path. The user is communicated on the secure location path through Webhooks.

The API offers a sandbox environment for you to test the characteristics of the actual production environment and to obtain simulated responses from all API methods. In order to access the sandbox environment, the user needs to raise a request for developer access to the Taxbandits API.

The request can be made through https://developer.taxbandits.com/Home/index

The API reviews the user request and in response creates a developer account for the user in the sandbox environment. Once the account is created, the user will receive an email on the credentials that include the public and private keys for accessing the developer account through https://sandbox.taxbandits.com. At the time of API handshake, these keys will be used for identifying the user and to encrypt the message.

API Previewer Tool
You can check how a JSON is generated for an API method in the API previewer tool. Choose the API method and click the JSON Generator button.



This tool has an option to capture the user-defined fields and corresponding values expected in the JSON Request. Once you key in the details, the same will be converted to a JSON format.

The API has gone to greater lengths to safeguard users’ data from theft and other potential hacks and threats. Our improved data security architecture protects the data shared through API.

While the application subjects the data in rest to an end-to-end encryption process, data in transit are protected from malware attacks and other intrusions through robust network control protocols.

API Security
The API uses secure JSON parsers and strongly typed data to avert data intrusion. In order to clearly identify and address the errors, the status of API methods is communicated through HTTP codes.

Data in transit are protected by restricting the access received only from Secure Tunnel (TLS) and whitelisted IP addresses. Parallely, the API authenticates the messages and verifies the user identify through HMAC authentication and user tokens, respectively.

To protect the API against replay attacks, the idea of Nonce is implemented. The nonce is a random or pseudo-random number issued in an authentication protocol to ensure that old communications cannot be reused in replay attacks.

Hash-based message authentication code (HMAC)
The API uses a Hash-based message authentication code (HMAC) to validate the integrity and authenticity of the request received. Through HMAC, the message is encrypted using the SHA-256 algorithm involving a hash function in combination with a secret key. The HMAC authentication digest is computed using a composite of the URL, request timestamp, and a secret key.

The key identifier along with the digest, which is encoded using Base64, is combined and added to the authorization header. Once the data are received at the API’s end, the system recalculates the HASH and matches it with the user-sent HASH. This way the user is identified and the message is authenticated.

The API uses some common object fields across all API Endpoints so as to make referencing easier. As a user, gaining familiarity with these fields will help understand what needs to be sent in the Request and how to interpret the data received in the Response.

Submission ID
Let’s presume that a request is sent to the CREATE API Endpoint. This request can have the data of multiple clients or a single client. Once the request hits the Endpoint, a submission ID is created.

What happens is that the information contained in a single request is tagged to a Submission ID. This is a GUID created at the API end and will be notified back to the sender (you) as part of the Response. From now on, the user must reference this Submission ID in the follow-up requests initiated for Update, Delete, Validate, List, Get and Transmit End Points.

Record ID
A unique GUID is assigned to every form that is created by the API. This ID must be referenced for any follow-up requests.

For example, if a user wants to delete a few forms that were created by the API, a request needs to be sent with the Submission ID and Record ID. Accordingly, the API will delete the forms tagged to that Record ID.

Sequence
It is a unique number that the sender assigns to each record at the time of submission. Since the records are not created at this juncture, record ID would not have been created and thus identifying the list of failed records from a large group becomes difficult. That’s where the object field Sequence comes into play. In case the records are errored out, the 'Sequence' may be used at the receiver end to identify the records. The sender has to pass this as part of the request against each of the form data.

The response will have the Sequence along with the error details so that it’s easier to pull the record and make necessary corrections before submitting it again.

The API uses webhooks to notify users on the status of tax forms filed. Through this, the API gains an advantage to send a notification through an HTTP post as well as to respond to the same request more information.

The user must configure webhooks from the developer control panel. Right now, the scope of this communication is limited to the status of tax forms.



Configure webhook

1. Log in to the developer control panel. Go to Settings >> Webhooks.


2. Enter the Callback URL and click on the Submit button. Ensure that the callback URL is valid as the API will post a sample JSON. The callback URL is expected to return HTTP 200 response code in order to remain active. If the API doesn’t return 200 response code, then the callback URL will go to inactive. You can retry posting the sample data to make the callback URL Active.

Receive webhook request from API
The API will issue an HTTP Post to the webhook URL every time when the status gets updated for a tax return. The request’s POST parameter will contain JSON data.

Respond to a webhook request from API
The user must respond to the webhook request by sending an HTTP 200 OK Response. Any other code other than 200 will be treated as an incomplete call. This API does not support 301 redirects, which will be treated as an error.

You are required to initiate a response to our webhook request within 5 seconds, if not, the request will be treated as timeout. If the API doesn’t receive a response during the 5-second time window or in case of an error, it will attempt to retry the connection for a total of 9 times over the next 24 hours.

We recommend users to respond to the webhook request at the earliest before initiating other internal communication processes. For example, if you wish to notify users whose returns were rejected by the IRS, the first thing you should do is to initiate a response to the webhook event by giving HTTP 200 OK response, and then attempt to email the rejected users. In this way, sending emails doesn’t get blocked while responding to webhook.

Security of Webhooks
Before you respond to a webhook request, validate if the request has been sent by the Taxbandits Webhooks. To verify the authenticity, check if the webhook post has the signature on the header. And then, match it with the HMAC digest computed using the algorithm below. If both the components match, you can be assured that the webhook request was sent by Taxbandits.

Below is what you need to do:
Step: 1 Retrieve the Public Key from the user repository. This is the same public key that was provided in the developer control panel.

Step: 2 Read the Timestamp and the Signature from the header.

Step: 3 Use the Public Key and the Timestamp to compute the HMAC hash using SHA 256 algorithm.

Step: 4 The signature generated in the header must match with the hash generated with Step 3.

• If there is a match, parse the JSON data for further processing.
• If there is no match, send the Response as 401 and stop processing.

The API uses the commonly used error codes to stream the success or failure message to an API request. If validation checks fail during the creation of the business, the field errors will return the information in the Response, which may be handled at the client’s end. There are three components in error handling as outlined below.

Error Structure

HTTP Status Codes
HTTP status codes are reported back in the Response JSON. Below is how the HTTP status codes are grouped:

S No.	Code	Status	Description
1	200	Ok	Successful API call
2	300	Multi-Status	Multiple statuses are available for the request.
3	400	BadRequest	A validation error has occurred.
4	401	Unauthorized	Invalid authorization credentials.
5	402	CreditsNotSufficient	The Credit in your account is not sufficient to transmit all requested records
6	404	NotFound	The resource you have specified cannot be found
7	405	MethodNotAllowed	The Credit in your account is not sufficient to transmit all requested records
8	429	RequestLimitExceeded	The API rate limit for your organisation/application has been exceeded
9	500	InternalServerError	An unhandled error with this API call. Contact the API team if problems persist
10	503	NotAvailable	API is currently unavailable – typically due to a scheduled outage – try again soon

Data validation errors
Before processing the individual records, the API subjects the data to some mandatory data validation checks, and errors observed will be reported under the object “Errors”.



Business validation errors
To process the individual records, the data is subjected to business validation checks, and errors observed will be reported under the object “ErrorRecords”.