TaxBandits SDK is available in several commonly used programming languages. We are currently providing SDKs in .NET, Java, PHP & Python.

Prerequisites​

Listed below are the important URLs in the Sandbox environment: ● Developer Console: sandbox.taxbandits.com

● Application: testapp.taxbandits.com

● API: [testapi.taxbandits.com]/version

● Authentication API: [testoauth.expressauth.net/v2/tbsauth]

To get started with TaxBandits API, users have to sign up for our Sandbox environment. After logging in, navigate to Settings >> API Credentials to receive the following authentication keys:

• Client ID

• Client secret

• User Token

Note: Do not share the keys with any individual or business. For a quick guide on steps to receive access token (JWT), read our article on Security of TaxBandits API & Guide to OAuth 2.0 Authentication.

A few code snippets from .NET SDK using JWT​

Below is a sample code snippet to hit Form 941 Create endpoint along with the OAuth authentication logics:

To start with, set the appropriate keys in the App.config file as shown below:

*<!--URLs-->* 
    <add key="OAuthApiUrl" value="https://testoauth.expressauth.net/v2/" />
    <add key="PublicAPIUrlWithJWT" value="https://testapi.taxbandits.com/v1.6.0/" />
    <add key="OAuthApiMethodRoute" value="tbsauth" />
    
 *<!--JWT Credentials from Dev Console (Settings ==> API Credentials)-->*
    <add key="ClientId" value="--Your ClientId here--" />
    <add key="ClientSecret" value="--Your ClientSecret here--" />
    <add key="UserToken" value="--Your UserToken here--" />

Retrieve classes to construct a 941 CREATE request from TaxBandits SDK. Running the .NET SDK can help you provide test values in a UI & submit them.

On submitting the above form, the following code snippet gets executed:

//Get URLs from App.Config
                string oAuthApiUrl = Utility.GetAppSettings("OAuthApiUrl");
                string apiUrl = Utility.GetAppSettings("PublicAPIUrlWithJWT");

                //Call OAuth API 
                using (var oAuthClient = new HttpClient())
                {
                    string oAuthRequestUri = Utility.GetAppSettings("OAuthApiMethodRoute");
                    oAuthClient.BaseAddress = new Uri(oAuthApiUrl);

                    //Generate JWS and get access token (JWT)
                    OAuthGenerator.GenerateJWSAndGetAccessToken(oAuthClient);

                    //Read OAuth API response
                    var response = oAuthClient.GetAsync(oAuthRequestUri).Result;
                    if (response != null && response.IsSuccessStatusCode)
                    {
                        var oauthApiResponse = response.Content.ReadAsAsync<AccessTokenResponse>().Result;
                        if (oauthApiResponse != null && oauthApiResponse.StatusCode == 200)
                        {
                            //Get Access token from OAuth API response
                            string accessToken = oauthApiResponse.AccessToken;
                            //Access token is valid for one hour. After that call OAuth API again & get new Access token.

                            if (!string.IsNullOrWhiteSpace(accessToken))
                            {
                                //Call TaxBandits API using the Access token
                                //Access token is valid for one hour. After that call OAuth API again & get new Access token.
                                using (var apiClient = new HttpClient())
                                {
                                    //API URL to Create Form 941 Return
                                    string requestUri = "Form941/Create";

                                    apiClient.BaseAddress = new Uri(apiUrl);

                                    //Construct HTTP headers
                                    //If the Access token got expired, call OAuth API again & get a new Access token.
                                    OAuthGenerator.ConstructHeadersWithAccessToken(apiClient, accessToken);

                                    //Get Response
                                    var apiResponse = apiClient.PostAsJsonAsync(requestUri, form941ReturnList).Result;
                                    if (apiResponse != null && response.IsSuccessStatusCode)
                                    {
                                        //Read Response
                                        var createResponse = apiResponse.Content.ReadAsAsync<Form941CreateReturnResponse>().Result;
                                        if (createResponse != null)
                                        {
                                            responseJson = JsonConvert.SerializeObject(createResponse, Formatting.Indented);
                                            //Deserializing JSON (Success Response) to Form941CreateReturnResponse object
                                            form941Response = new JavaScriptSerializer().Deserialize<Form941CreateReturnResponse>(responseJson);
                                            if (form941Response.SubmissionId != null && form941Response.SubmissionId != Guid.Empty)
                                            {
                                                //Adding Form941CreateReturnResponse Response to Session
                                                APISession.AddForm941APIResponse(form941Response);
                                            }
                                        }
                                    }
                                    else
                                    {
                                        var createResponse = apiResponse.Content.ReadAsAsync<Object>().Result;
                                        responseJson = JsonConvert.SerializeObject(createResponse, Formatting.Indented);

                                        //Deserializing JSON (Error Response) to Form941CreateReturnResponse object
                                        form941Response = new JavaScriptSerializer().Deserialize<Form941CreateReturnResponse>(responseJson);
                                    }
                                }
                            }
                        }
                    }
                }

The sample below is a create request JSON of Form 941. For a more detailed explanation of the individual JSON, fields refer to our documentation site.

{
"Form941Records": [
    {
        "SequenceId": "001",
        "ReturnHeader": {
            "ReturnType": "FORM941",
            "TaxYr": "2023",
            "Qtr": "Q1",
            "Business": {
                "BusinessId": null,
                "BusinessNm": "Meefto Bridge Company",
                "TradeNm": " Meefto",
                "IsEIN": true,
                "EINorSSN": "865626415",
                "Email": "John@gmail.com",
                "ContactNm": "Alice John",
                "Phone": "9894216412",
                "PhoneExtn": null,
                "Fax": "3236415281",
                "BusinessType": "ESTE",
                "SigningAuthority": {
                    "Name": "Tina Charles",
                    "Phone": "7498798798",
                    "BusinessMemberType": "ADMINISTRATOR"
                },
                "KindOfEmployer": null,
                "KindOfPayer": null,
                "IsBusinessTerminated": false,
                "IsForeign": true,
                "USAddress": {
                    "Address1": "1751 Kinsey Rd",
                    "Address2": "Main St",
                    "City": "Dothan",
                    "State": "AL",
                    "ZipCd": "36303"
                },
                "ForeignAddress": {
                    "Address1": "1751 Kinsey Rd",
                    "Address2": "Main St",
                    "City": "Dothan",
                    "ProvinceOrStateNm": "NY",
                    "Country": "UK",
                    "PostalCd": "78867789"
                }
            },
            "IsThirdPartyDesignee": false,
            "ThirdPartyDesignee": {
                "Name": null,
                "Phone": null,
                "PIN": null
            },
            "SignatureDetails": {
                "SignatureType": "ONLINE_SIGN_PIN",
                "OnlineSignaturePIN": {
                    "PIN": "1262441864"
                },
                "ReportingAgentPIN": {
                    "PIN":null
                },
                "taxPayerPIN": {
                    "PIN": null
                },
                "Form8453EMP": null
            },
            "BusinessStatusDetails": {
                "IsBusinessClosed": false,
                "BusinessClosedDetails": {
                    "Name": null,
                    "FinalDateWagesPaid": null,
                    "IsForeign": false,
                    "USAddress": {
                        "Address1": "1751 Kinsey Rd",
                        "Address2": "Main St",
                        "City": "Dothan",
                        "State": "AL",
                        "ZipCd": "36303"
                    },
                    "ForeignAddress": {
                        "Address1": "1751 Kinsey Rd",
                        "Address2": "Main St",
                        "City": "Dothan",
                        "ProvinceOrStateNm": "NY",
                        "Country": "UK",
                        "PostalCd": "78867789"
                    }
                },
                "IsBusinessTransferred": false,
                "BusinessTransferredDetails": {
                    "Name": null,
                    "BusinessChangeType": null,
                    "DateOfChange": null,
                    "NewBusinessType": null,
                    "NewBusinessName": null,
                    "IsForeign": true,
                    "USAddress": {
                        "Address1": null,
                        "Address2": null,
                        "City": null,
                        "State": null,
                        "ZipCd": null
                    },
                    "ForeignAddress": {
                        "Address1": "1751 Kinsey Rd",
                        "Address2": "Main St",
                        "City": "Dothan",
                        "ProvinceOrStateNm": "NY",
                        "Country": "UK",
                        "PostalCd": "78867789"
                    }
                },
                "IsSeasonalEmployer": false
            }
        },
        "ReturnData": {
            "Form941": {
                "EmployeeCnt": 200,
                "WagesAmt": 1264000.32,
                "FedIncomeTaxWHAmt": 248000.32,
                "WagesNotSubjToSSMedcrTaxInd": false,
                "SocialSecurityTaxCashWagesAmt_Col1":14502.32,
                "QualSickLeaveWagesAmt_Col1": 14280.64,
                "QualFamilyLeaveWagesAmt_Col1": 11520.32,
                "TaxableSocSecTipsAmt_Col1": 1420.36,
                "TaxableMedicareWagesTipsAmt_Col1": 11512.64,
                "TxblWageTipsSubjAddnlMedcrAmt_Col1": 7832.16,
                "SocialSecurityTaxAmt_Col2": 1798.29,
                "TaxOnQualSickLeaveWagesAmt_Col2": 885.40,
                "TaxOnQualFamilyLeaveWagesAmt_Col2": 714.26,
                "TaxOnSocialSecurityTipsAmt_Col2": 176.12,
                "TaxOnMedicareWagesTipsAmt_Col2": 333.87,
                "TaxOnWageTipsSubjAddnlMedcrAmt_Col2": 70.49,
                "TotSSMdcrTaxAmt":3978.43,
                "TaxOnUnreportedTips3121qAmt": 11204.62,
                "TotalTaxBeforeAdjustmentAmt": 263183.37,
                "CurrentQtrFractionsCentsAmt": 5200.36,
                "CurrentQuarterSickPaymentAmt": 16412.28,
                "CurrQtrTipGrpTermLifeInsAdjAmt": 5420.32,
                "TotalTaxAfterAdjustmentAmt":290216.33,
                "PayrollTaxCreditAmt": 1154.15,
                "IsPayrollTaxCredit": true,
                "Form8974": {
                    "Form8974IncomeTaxDetails": [
                        {
                            "IncomeTaxPeriodEndDate": "07-07-2021",
                            "IncomeTaxReturnFiledForm": "FORM1065",
                            "IncomeTaxReturnFiledDate": "07-07-2021",
                            "Form6765EIN": "006548956",
                            "Form6765Line44Amt": 5000,
                            "PreviousPeriodRemainingCreditAmt": 100,
                            "RemainingCredit": 4900
                        }
                    ],
                    "Line7": 4900,
                    "Line8": 1798.29,
                    "Line9": 176.12,
                    "Line10": 1974.41,
                    "Line11": 987.21,
                    "PayerIndicatorType": "SECTION3121QIND",
                    "Line12": 987.21,
                    "Line13": 3912.79,
                    "Line14": 333.87,
                    "Line15": 166.94,
                    "Line16": 166.94,
                    "Line17": 1154.15
                },
                "NonRfdCrQualSickAndFamilyWagesB4_Apr1_2021": 0,
                "NonRfdCrQualSickAndFamilyWagesAfter_Mar31_2021AndB4_Oct1_2021": 15248.63,
                "TotlNonRfdCrAmt":16402.78,
                "TotTaxAfterAdjustmentAndNonRfdCr": 273813.55,
                "TotTaxDepositAmt":13248.12,
                "RfdCrQualSickAndFamilyWagesB4_Apr1_2021": 12126.32,
                "RfdCrQualSickAndFamilyWagesAfter_Mar31_2021AndB4_Oct1_2021": 1218.44,
                "TotDepositAndRfdCrAmt": 26592.88,
                "BalanceDueAmt": 247220.67,
                "OverpaidAmt": 0,
                "OverPaymentRecoveryType": null,
                "QualHealthPlanExpToSickLeaveWagesB4_Apr1_2021": 1200.66,
                "QualHealthPlanExpToFamilyLeaveWagesB4_Apr1_2021": 1520.64,
                "QualSickLeaveWagesAfter_Mar31_2021AndB4_Oct1_2021": 14282.34,
                "QualHealthPlanExpToSickLeaveWagesAfter_Mar31_2021AndB4_Oct1_2021": 12118.66,
                "CBAToSickLeaveWagesAfter_Mar31_2021AndB4_Oct1_2021": 5420.66,
                "QualFamilyLeaveWagesAfter_Mar31_2021AndB4_Oct1_2021": 55281.44,
                "QualHealthPlanExpToFamilyLeaveWagesAfter_Mar31_2021AndB4_Oct1_2021": 291864.32,
                "CBAToFamilyLeaveWagesAfter_Mar31_2021AndB4_Oct1_2021": 1840.32
            },
            "IRSPaymentType": "EFTPS",
            "IRSPayment": {
                "BankRoutingNum": null,
                "AccountType": null,
                "BankAccountNum": null,
                "Phone": null
            },
            "DepositScheduleType": {
                "DepositorType": "MONTHLY",
                "MonthlyDepositor": {
                    "TaxLiabilityMonth1":50000.00,
                    "TaxLiabilityMonth2": 173813.55,
                    "TaxLiabilityMonth3": 50000.00
                },
                "SemiWeeklyDepositor": null,
                "TotalQuarterTaxLiabilityAmt": 273813.55
            }
        }
    }
]

}

Be sure to check out our documentation site for more sample JSONs and their field explanation of all the forms we support in TaxBandits API.

For any further assistance, feel free to contact our 24*7 South Carolina-based support team at 704.684.4751 or send us an email to developer@taxbandits.com.

Our API Security

TaxBandits API has gone to the greatest lengths to safeguard our users' data from theft, hacks, and security threats. Our advanced data security architecture protects the data shared through API.

The application subjects the data in rest to an end-to-end encryption process. Data in transit is protected from malware attacks and other intrusions by robust network control protocols.

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 is protected by restricting the access to Secure Tunnels (TLS) and whitelisted IP addresses in the Live environment.

Security of Data at Rest​

Since we are dealing with confidential information, your data is secured while at rest. The data resides on databases, file systems, and other structured storage devices. The 'Always Encrypted' technique in MS SQL Server is used to store the data.

Database columns containing Personal Identifiable Information (PII) such as Name, DOB, SSN, and EIN are encrypted using a symmetric key with AES 256 algorithm and stored. PDFs and other documents are encrypted with the AES-256 algorithm and are stored in AWS S3. The database connection information is also encrypted using the AES algorithm.

Security of Data when in Use​

We don't store information if we don't have to. For example, a reference to the credit card profile is all that is maintained at our end. The actual data is stored with our merchant gateway, with very stringent security measures.

All activities are logged and periodically reviewed. This includes IP addresses, devices, and browsers used to access the data. As for the IRS, TIN masking is done to reduce the risk of identity theft. Our support systems have Multi-Factor Authentication and IP whitelisting to prevent unauthorized access.

OAuth 2.0 Authentication​

OAuth2.0 is an HTTP authentication standard, that involves a security token called Access token or JSON Web Token (JWT). Each request is authorized by validating the access token.

The access token is a cryptic string, usually generated by the server in response to a request with JSON Web Signature (JWS). The client must send this JWT in the Authorization header when making requests to protected resources.

The OAuth2.0 authentication is available on the version 1.5.0 and above in TaxBandits API.

Pre-requisites​

Below are the important URLs for the Sandbox environment: ● Developer Console: sandbox.taxbandits.com

● Application: testapp.taxbandits.com

● API: [testapi.taxbandits.com]/version

● Authentication API: [https://testoauth.expressauth.net/v2/tbsauth]

To get started with TaxBandits API, users have to sign up for our Sandbox environment. After logging in, navigate to Settings >> API Credentials to receive the following authentication keys:

• Client ID

• Client secret

• User Token

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

Steps to receive Access token (JWT) by constructing a JWS​

Construct a JWS according to OAuth 2.0 standards & hit our tbsauth endpoint in OAuth API in the Sandbox environment [https://testoauth.expressauth.net/v2/tbsauth] to receive an access token.

https://testoauth.expressauth.net/v2/tbsauth

The JWS consists of 3 parts

• Header

• Payload

• Signature

Each part of the JWS will be as illustrated below:

Header:

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

Payload:

{
"iss": "968a9c78dae29a29", /*Issuer: Client ID*/
"sub": "968a9c78dae29a29", /*Subject: Client ID*/
"aud": "a574b75f18b24fc09f9039ffb5cb08f3", /*Audience: User Token*/
"iat": 1516239022 /*Issued at: Current time (Unix epoch format)*/
}

Refer to this link for more information on the Unix Epoch standard.

Signature:

HMACSHA256(
base64UrlEncode(header) + ΓÇ£.ΓÇ¥ +
base64UrlEncode(payload),
siqHfLy59g3UHxrb5gjxg /*Client Secret retrieved from the console*/
)

Combine the header, payload, and signature concatenated with a dot (.) and applying HMACSHA256 algorithm to create the JWS.

Sample JWS:

eyJhbGciOiJIUzI1845CI6IkpXVCJ9.eyJpc3MiOi
I5NjhhOWM3OGRhZTI5YTI5Iiwi65412dfsfljNzhkYWUyOWEyOSIsImF1
ZCI6ImE1NzRiNzVmMThiMjRmYzA5ZjkwMzlmZmI1Y2IwOGYzIiwiaWF0IjoxN
TE2MjM5MDIyfQ.HNQznxlPyVt62ghfmewr1-uzm1uDWH4NBDLShA6Ac0

Below is the encoded & decoded structures of a JWS sample:

Once the JWS is created, then send a request to the OAuth server in the Sandbox environment with the JWS in Authentication HTTP header to get an Access token.

OAuth server receives JWS from the client & will validate to provide the JWT (Access token) to the client in the following response format:

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

This JWT (Access token) will be valid for one hour. On a JWT's expiry, repeat constructing JWS & hit OAuth server again to receive a new access token (JWT). We do not provide Refresh tokens.

Once the user obtains the JWT (Access token), its expiry can be known by decoding the JWT & reading its "exp"("ExpiresIn") claim value in the response. The user will have to use the same JWT along with every API request until the token expires.

Hitting TaxBandits API with JWT​

Every API request has to be sent along with the JWT in the Authorization HTTP header. TaxBandits Sandbox API URL is [https://testapi.taxbandits.com/version]

HTTP Headers required in every API request are:

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

Conclusion​

Our security team does internal audits at regular intervals and corrects any lapses. Our Quality Assurance team consists of members who test the security (Ethical Hackers) to find potential holes in the application. Code review workshops are held periodically and secure coding guidelines are taught and reviewed.

For more guidelines & code samples on integrating with TaxBandits, check out our TaxBandits SDK, which is available in several popular programming languages.

Error Handling:

TaxBandits 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.

What are the validations?​

● Mandatory/format validations, agency-specific data validations Ex: size, type, allowed characters, etc.,

● IRS/SSA Business Rules Validation (Math validations, Form conditions)

● USPS address validation (only for the postal orders)

When are the validations checked?​

● These validations are checked during the following API Endpoint method calls

a. Create —During the creation of the form. The validations must pass before the form will be created.

b. Update — Like the Create method, validations must pass before the form is updated.

c. Validate — This method performs validations on the created documents.

d. Transmit — When you call the Transmit method, we validate the form before it is transmitted.

e. ValidateForm — The validations are performed without creating the form.

How are the errors communicated?​

● The errors are communicated in the Response of Create, Update, Validate, ValidateForm, and Transmit methods.

● These errors will be communicated instantly in the Response JSON and each error has a unique Error Code that is used to track and resolve them.

How to correct it?​

● We will provide the Field Mapping, API Business Rules, IRS Business Rules, and Error Message documentation to help you resolve the validation errors that occur on your side.

● You can update the fields containing errors and call the methods again (Create, Update, Validate, or Transmit).

Error Structure

{
<← HTTP Status Code Fields →>
"StatusCode": 200,
 "StatusName": "Ok",
 "StatusMessage": "Successful API call",
<← Submission Detail →
"SubmissionId": "6a30078c-7e5f-4db0–862a-d5e1266363f0",
<← Form Success Details & Business Validation Errors →>
 "FormRecords": {
<← Collection of Form Success Details →
 SuccessRecords": {
 . . .
 },
<← Collection of Business Validation Error Details →
 "ErrorRecords": {
 . . .
 },
<← Collection of Data Validation Error Details →
 "Errors": {
 . . .
 }
}

HTTP Status Codes

HTTP status codes are reported back in the response JSON. The chart below shows how the HTTP status codes are grouped:

Data validation errors

Before processing individual records, the API subjects the data to some mandatory data validation checks. Any errors that are observed will be reported under the object "Errors".

"Errors": {
<<-- Error on an incorrect TIN format -->
    {
        "Id": "F00-100088",
        "Name": "Business.EINorSSN",
        "Message": "Enter a valid EINorSSN”
    }
}

Business validation errors

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

<<-- Collection of Business Validation Error -->
"ErrorRecords": {
<<-- Business Validation Errors on Record with Sequence 8 -->

    "RecordId": "0e6b053a-3e67-4559-a09f-5631bd06f5e9",
    "Sequence": "8",
    "Errors":
    {
       
<<-- Error on Recipient First Name required -->

        "Id": "F00-100239",
        "Name": "Recipient.FirstPayeeNm",
        "Message": "FirstPayeeNm is required",
           }
},

Best Practices

Business Object fields​

The Business Object is a common field in all the forms supported by TaxBandits API. So, when you file a new Form W-2, 941, 1099MISC, or 940, you can use the same Business Object created in any Endpoint and in other Endpoints too.

Since the Business Object is built for all types of forms, there will be optional fields which are not relevant to a particular form under the Business Object, you can leave those fields blank as they are non-mandatory.

Submission IDs and Record IDs​

Whenever you submit a request, a unique Submission ID will be sent to you on the response. You must use the Submission ID the next time you are using API calls like Update, Get, List, etc.

If a single submission has multiple records (Forms), a unique Record ID will be generated for each of the records (Forms). You can use the Record ID the next time when you are making the API calls like Update, Get, List etc. to work on a particular record.

Business ID or TIN​

When you create a Form W-2/1099MISC, a unique business ID will be created for the business. In the future, you can just use the business ID to work with that particular business.

You can either use the business ID or business's EIN/SSN to reference a business created. Please note: The EIN/SSN is unique to a business under the user account. If there is already a business with the same EIN/SSN, the details will be merged during the API Create method call.

Webhook URL — Reactivation​

If the Webhook delivery (Status or PDF) fails 18 times continuously when we try to send the Webhook responses to your URL, our system will stop sending the Webhook response and your webhook URL will be disabled on our end. Then you must change it back to Active by logging in to the console settings (Webhook Settings) page and revalidating the URL.

Store the IDs​

Submission ID, Business ID, and Record ID must be stored in order to call the consequent APIs.

Use Webhook to get statuses and pdf​

We strongly recommend that you configure the Webhook in a way that the status of the form and pdfs are received automatically. You do not have to use the Status and GetPDF methods each time to check the status of the returns and download the forms. We don't encourage continuous polling of our servers/APIs.

Sequence Number​

The sequence number under the Return object can be used for your reference. The sequence number should be unique for all the records in a single submission.

You can refer to the Submission ID and Sequence number the next time you want to refer to the particular return (Update, Get, Status etc.)

Cancel or Callback submission within 4 hours after Transmission​

Since our e-file system has an in-built 4 hours delay, this allows the developer to cancel/recall the forms for any corrections before the returns are submitted to the Agency.

Note: This option will be disabled during the last week of January.

Client communication within 24 hours​

As per the IRS guidelines, it is the responsibility of the Software Provider(TaxBandits) to take reasonable steps to inform the taxpayer of the rejection within 24 hours. Make sure, the Rejections posted by us on the Webhooks reach the taxpayer within the time frame. Although it is applicable to MeF platforms, we uphold the same timelines across all the Form types.

Refer IRS Publication for more information about this https://www.irs.gov/pub/irs-pdf/p4163.pdf

Whitelist IP Addresses (Live)​

If there is a change in IP address from your end, it is always advised to send the new IP to us before sending requests to our API. Only requests from whitelisted IPs can reach the API. Authentication errors will be thrown if you send requests from a non-whitelisted IP address.

TaxBandits E-file Rejections

After a form is transmitted using Transmit Method, TaxBandits E-File system takes over and does a series of validations and sends out the rejections:

● Field format and business rules validations on the converted data (As per the Agency Schema).

● Checks for Duplicate filings in TaxBandits

● Agency Specific File Format validations (EFW2, FIRE or MeF XML)

● Proprietary System Validations

● USPS address validations (only for the postal orders)

● Any missed validations from Stage 1

When are the validations applied?​

● These validations will be applied to the return before it is submitted directly to the appropriate Agency by TaxBandits E-File System once it is transmitted using the API.

● We have a built-in delay of 4 hours before the E-file System takes over and performs error checks. This delay can be used in the case that a user needs to cancel the submission or recall the return to edit it. Once the E-File system takes over, the processing of the form can not be stopped. This built-in delay will not be enforced during the 5 days of January when there is a massive volume of data running through our system processes.

How are the errors communicated?​

● These errors are communicated either via Webhook or the developer can pick up the errors using the Form Endpoint "Status" method.

● Webhook is the preferred way because the processing timings are unpredictable and we don't encourage polling of our API from your client application.

● These errors will be communicated within 24 hours after the return is Transmitted to our system.

● The Status of the Return will change to "Rejected"

How to correct errors?​

● You can update the fields containing errors and use the Update, Validate and Transmit methods to retransmit the return

● The corrections are applied to the same W-2/1099 Form — no new form or correction forms are necessary.

● The credits will not be deducted for the Forms that are Rejected and Retransmitted.

Federal Agency Rejections

These rejections come directly from the IRS (for 1099) or SSA (for W2). Once the returns pass through E-File validations (as above), our system will hand it over to the Federal Agency for processing. Although we experience very few rejections, we still get a few, typically for the following reasons:

● Duplicate filing for the same tax year or quarter. The client could have paper filed or e-filed it elsewhere (Check on the Agency's database).

● The Business name and EIN does not match (Checked on the Agency's database)

● The return should not have been filed for legal reasons.

When are the validations checked?​

These errors will be checked on the Federal Agency's side after we submit the return to them.

How are these errors communicated?​

The amount of time that it takes agencies to process returns can vary greatly. It generally depends on the volume of returns that are trying to process at a given time. Our system picks up the errors from the Federal Systems and is mandated to communicate to clients within 24 hours.

● These errors are communicated either by Webhook or developers can pick up the errors using the Form Endpoint "Status" method. We prefer the Webhook method of communicating the errors

● The Status of the Return will change to "Rejected".

How to correct the errors?​

● You can update the fields with the errors and use the methods Update, Validate and Transmit to retransmit the return

● The corrections are applied to the same W-2/1099 Form — no new form or correction forms are necessary.

● The credits will not be deducted for the Forms that are Rejected and Retransmitted.

State Agency Rejections

These are rejections from the respective state agencies. Rules vary completely for each state and this can become highly complicated. Some states require unique values for the employee W2 data and some states demand specific information from the employer (Tax Liability, Tax Deposit information) before processing the W2 forms. While rejections are rare, here are the most common reasons why they occur.

● State agency-specific rejections based on state business rules

● State Reconciliation form field errors

● The State ID number didn't match the State Database

When are the validations checked?​

These errors will be checked on the State Agency's side after we submit the return to them.

How are these errors communicated?​

States process the returns at an unpredictable pace. Our system picks up the errors from the state systems for processing.

● These errors are communicated either via Webhook or the developer can pick up the errors using the Form Endpoint "Status" method. Again, we prefer the Webhook method of communicating the errors.

● The Status of the Return will change to "Rejected".

● The response time of these errors solely depends on the state.

How to correct it?​

● You can update the fields containing errors by using the methods Update, Validate and Transmit to retransmit the return.

● The corrections are applied to the same W-2/1099 Form — no new form or correction forms are necessary.

● The credits will not be deducted for the Forms that are Rejected and Retransmitted.

Conclusion

Handling errors & rejections are made easier with the error handling techniques we offer.

Follow our instructions on best practices for a better understanding of how to file your returns.