Documentation
REQUEST ACCESS

Tax Profile

Suggest Edits

Once you have registered a user, you can easily set your user up to get accurate tax estimates, by following the below steps.

1. Getting the user's tax profile

The Hurdlr Tax Calculations API combines robustness with the flexibility that your user base needs. Hurdlr can provide useful tax estimates with very minimal data. And, as you are able to gather more tax-related data from your user, the estimates will get more accurate.

First, you should retrieve the user's tax profile. Be sure to include that user's access_token in the headers.

curl \
  --request GET \
  --url https://sandbox.hurdlr.com/rest/v5/taxes/userTaxSetup \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \

The response from GET /userTaxSetup contains a JSON object, with the user's current tax profile:

{
  // Basic tax fields
  "id": 4241,
  "taxCountryCode": "USA",
  "federalFilingStatus": "SINGLE",
  "stateFilingStatus": "SINGLE",
  "taxState": null,
  "annualW2Income": 0,
  "acceptedDisclaimer": false,
  "isSetupComplete": false,
  
  //Advanced tax fields
  "useW2Withholding": false,
  "federalW2Withholding": 0,
  "stateW2Withholding": 0,
  "numExemptions": 1,
  "useHomeOfficeDeduction": null,
  "homeOfficeArea": null, 
  "userEstimatedAnnualRevenue": 0,
  "useUserEstimatedRevenueForTaxCalc": false,
    
  // Canada-specific tax fields
  "spouseIncome": 0,
  "numDependents": 0,
  "dependentIncome": 0,
  "useUserEstimatedVehicleBusinessPercent": false,
  "vehicleBusinessPercent": 50,
  "autoSalesTax": false,
  "lastUpdatedDate": "2019-03-08T15:12:48.000Z"
}

2. Updating the user's tax profile

You should consider updating the following condensed set of fields on your user's tax profile, as part of your initial tax onboarding:

FieldDescriptionFormat
federalFilingStatusFiling status used for Federal tax filingMust be one of the following: "SINGLE", "MARRIED", "MARRIED_SEPARATELY", "HEAD", "WIDOWER"
stateFilingStatusFiling status used for State tax filing; usually the same as Federal, but there are situations where the filing status can differMust be one of the following: "SINGLE", "MARRIED", "MARRIED_SEPARATELY", "HEAD", "WIDOWER"
taxStateTwo-letter state/province abbreviationString
annualW2IncomeEstimate of the user's annual W-2 paystubs total, before any tax withholdingsNumeric, with 2 decimal places
acceptedDisclaimerWhether the user has accepted your tax disclaimerBoolean
isSetupCompleteWhether the user has completed your initial tax onboardingBoolean

Optional data attributes, which you may want to allow your user to edit in a more advanced tax profile settings screen, are listed below:

FieldDescriptionFormat
useW2WithholdingWhether the user has specified their W-2 withholdings (allows for more accurate tax estimates); when not specified, Hurdlr estimates the W-2 withholding amountBoolean
federalW2WithholdingFederal tax amount withheld from W-2 income; required if useW2Withholding is trueNumeric, with 2 decimal places
stateW2WithholdingState tax amount withheld from W-2 income; required if useW2Withholding is trueNumeric, with 2 decimal places
numExemptionsNumber of state tax exemptions that the user qualifies forNumeric
useHomeOfficeDeductionWhether the user wants to use the simplified option for home office deductionBoolean
homeOfficeAreaSize of the home office, in sq. feet (not to exceed 300)Numeric, with 2 decimal places
useUserEstimatedRevenueForTaxCalcWhether the user (or developer) wants to override Hurdlr's annual business income projection with their own estimate; this will impact annual and quarterly tax estimatesBoolean
userEstimatedAnnualRevenueUser's estimated annual business incomeNumeric, with 2 decimal places

To update the user's tax profile, simply POST the updated JSON object to the /userTaxSetup endpoint:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/taxes/userTaxSetup \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
  	"userTaxSetup": {
      "taxCountryCode": "USA",
      "federalFilingStatus": "MARRIED_SEPARATELY",
      "stateFilingStatus": "MARRIED_SEPARATELY",
      "taxState": DC,
      "annualW2Income": 30000,
      "acceptedDisclaimer": true,
      "isSetupComplete": true,
      "numExemptions": 1,
      "useHomeOfficeDeduction": false,
      "homeOfficeArea": null, 
      "userEstimatedAnnualRevenue": 0,
      "useUserEstimatedRevenueForTaxCalc": false,
      "useW2Withholding": true,
      "federalW2Withholding": 5000,
      "stateW2Withholding": 1000,
    }
  }'

📘

Submitting Quarterly Tax Payments to the IRS

If you are interested in allowing your users to submit estimated tax payments to the IRS, you may need to update a few extra attributes in the user's tax profile, to update their 1040-ES tax filer info.

3. Displaying a tax disclaimer

While the Hurdlr API provides tax estimates, you will likely want to display a disclaimer to your users to relieve yourself of any potential tax-related liabilities. We recommend displaying the following language in your tax onboarding:

<Your app name> tax calculations are estimates and are not actual amounts owed.
They are provided for informational purposes only and should not be construed as
financial or tax advice (or a substitute for obtaining such advice), or for the 
purpose of avoiding U.S. Federal, State, or Local tax payments and penalties.

By clicking the button below, I understand the above and still want to use this feature.

Once the user accepts the disclaimer, we recommend that you update the user's tax profile to set isSetupComplete to true. That way, you can prove that your user has agreed to the disclaimer.

Updated over 1 year ago