Exploring SDK of TaxBandits API
5 min readNov 23, 2020
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/v1/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/v1/" />
<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": [
{
"Sequence": null,
"ReturnHeader": {
"ReturnType": "FORM941",
"MoreClients": false,
"TaxYr": "2020",
"Qtr": "Q3",
"Business": {
"BusinessId": null,
"BusinessNm": "Fomby Trucking LLC",
"TradeNm": null,
"IsEIN": true,
"EINorSSN": "003587734",
"Email": "developer@taxbandits.com",
"ContactNm": "Tina Charles",
"Phone": "1654798798",
"PhoneExtn": null,
"Fax": "5649879878",
"BusinessType": "CORP",
"SigningAuthority": {
"Name": "Tina Charles",
"Phone": "7498798798",
"BusinessMemberType": "PRESIDENT"
},
"KindOfEmployer": null,
"KindOfPayer": null,
"IsBusinessTerminated": false,
"IsForeign": false,
"USAddress": {
"Address1": "1751 Kinsey Rd",
"Address2": "Main St",
"City": "Dothan",
"State": "AL",
"ZipCd": "36303"
},
"ForeignAddress": {
"Address1": null,
"Address2": null,
"City": null,
"ProvinceOrStateNm": null,
"Country": null,
"PostalCd": null
}
},
"IsThirdPartyDesignee": false,
"ThirdPartyDesignee": {
"Name": null,
"Phone": null,
"PIN": null
},
"SignatureDetails": {
"SignatureType": "ONLINE_SIGN_PIN",
"OnlineSignaturePIN": {
"PIN": "4564564555"
},
"ReportingAgentPIN": {
"PIN": null
},
"Form8453EMP": null
},
"BusinessStatusDetails": {
"IsBusinessClosed": false,
"BusinessClosedDetails": {
"Name": null,
"FinalDateWagesPaid": null,
"IsForeign": false,
"USAddress": {
"Address1": null,
"Address2": null,
"City": null,
"State": null,
"ZipCd": null
},
"ForeignAddress": {
"Address1": null,
"Address2": null,
"City": null,
"ProvinceOrStateNm": null,
"Country": null,
"PostalCd": null
}
},
"IsBusinessTransferred": false,
"BusinessTransferredDetails": {
"Name": null,
"BusinessChangeType": null,
"DateOfChange": null,
"NewBusinessType": null,
"NewBusinessName": null,
"IsForeign": false,
"USAddress": {
"Address1": null,
"Address2": null,
"City": null,
"State": null,
"ZipCd": null
},
"ForeignAddress": {
"Address1": null,
"Address2": null,
"City": null,
"ProvinceOrStateNm": null,
"Country": null,
"PostalCd": null
}
},
"IsSeasonalEmployer": false
}
},
"ReturnData": {
"Form941": {
"EmployeeCnt": 235,
"WagesAmt": 50000.85,
"FedIncomeTaxWHAmt": 8000.21,
"WagesNotSubjToSSMedcrTaxInd": true,
"SocialSecurityTaxCashWagesAmt_Col1": 45000.85,
"TaxableSocSecTipsAmt_Col1": 2500,
"TaxableMedicareWagesTipsAmt_Col1": 50000.85,
"TxblWageTipsSubjAddnlMedcrAmt_Col1": 2500,
"SocialSecurityTaxAmt_Col2": 5580.11,
"TaxOnSocialSecurityTipsAmt_Col2": 310,
"TaxOnMedicareWagesTipsAmt_Col2": 1450.02,
"TaxOnWageTipsSubjAddnlMedcrAmt_Col2": 22.5,
"TotSSMdcrTaxAmt": 12942.73,
"TaxOnUnreportedTips3121qAmt": 80.21,
"TotalTaxBeforeAdjustmentAmt": 21023.15,
"CurrentQtrFractionsCentsAmt": -20.11,
"CurrentQuarterSickPaymentAmt": -20.1,
"CurrQtrTipGrpTermLifeInsAdjAmt": -20,
"TotalTaxAfterAdjustmentAmt": 20962.94,
"PayrollTaxCreditAmt": 1000,
"TotTaxAmt": 19561.24,
"IsPayrollTaxCredit": true,
"Form8974": {
"Form8974IncomeTaxDetails": [
{
"IncomeTaxPeriodEndDate": "07-07-2020",
"IncomeTaxReturnFiledForm": "FORM1065",
"IncomeTaxReturnFiledDate": "07-07-2020",
"Form6765EIN": "006548956",
"Form6765Line44Amt": 2000,
"PreviousPeriodRemainingCreditAmt": 1000,
"RemainingCredit": 1000
}
],
"Line7": 1000,
"Line8": 5580.11,
"Line9": 310,
"Line10": 5890.11,
"Line11": 2945.06,
"PayerIndicatorType": null,
"Line12": 1000
},
"TotTaxDepositAmt": 10000.37,
"BalanceDueAmt": 0,
"OverpaidAmt": 10439.87,
"OverPaymentRecoveryType": "Refund",
"FilerType": null
},
"COVIDSection": {
"QualSickLeaveWagesAmt_Col1": 45000.85,
"QualFamilyLeaveWagesAmt_Col1": 45000.85,
"TaxOnQualSickLeaveWagesAmt_Col2": 2790.05,
"TaxOnQualFamilyLeaveWagesAmt_Col2": 2790.05,
"NonRfdCrQualSickAndFamilyWagesAmt": 200.85,
"NonRfdEeRetentionCrAmt": 200.85,
"TotlNonRfdCrAmt": 1401.7,
"DeferredAmtErSSTax": 0,
"DeferredAmtSSTax": 10000.37,
"RfdCrQualSickAndFamilyWagesAmt": 10000.37,
"RfdEeRetentionCrAmt": 10000.37,
"TotDepositDeferralAndRfdCrAmt": 40001.48,
"TotAdvRcvd7200": 10000.37,
"TotDepositsDeferralsAndRfdCrLessAdvAmt": 30001.11,
"QualHealthPlanExpToSickLeaveWagesAmt": 200.55,
"QualHealthPlanExpToFamilyLeaveWagesAmt": 200.55,
"QualWagesForEeRetentionCrAmt": 200.55,
"QualHealthPlanExpToWagesAmt": 200.55,
"Form5884CCr": 200.55,
"QualWagesPaidMar13To31": 0,
"QualHealthPlanExpMar13To31": 0,
"DeferredAmtEESSTax": 200.55
},
"IRSPaymentType": null,
"IRSPayment": {
"BankRoutingNum": null,
"AccountType": null,
"BankAccountNum": null,
"Phone": null
},
"DepositScheduleType": {
"DepositorType": "MONTHLY",
"MonthlyDepositor": {
"TaxLiabilityMonth1": 5000,
"TaxLiabilityMonth2": 5000,
"TaxLiabilityMonth3": 9561.24
},
"SemiWeeklyDepositor": null,
"TotalQuarterTaxLiabilityAmt": 19561.24
}
},
"RecordId": null
}
]
}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.
