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.

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 and EIN. 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 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 18 times over the next 48 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 ExpressTruckTax 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 ExpressTruckTax.

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.