Tax Profile

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:

Field	Description	Format
federalFilingStatus	Filing status used for Federal tax filing	Must be one of the following: "SINGLE", "MARRIED", "MARRIED_SEPARATELY", "HEAD", "WIDOWER"
stateFilingStatus	Filing status used for State tax filing; usually the same as Federal, but there are situations where the filing status can differ	Must be one of the following: "SINGLE", "MARRIED", "MARRIED_SEPARATELY", "HEAD", "WIDOWER"
taxState	Two-letter state/province abbreviation	String
annualW2Income	Estimate of the user's annual W-2 paystubs total, before any tax withholdings	Numeric, with 2 decimal places
acceptedDisclaimer	Whether the user has accepted your tax disclaimer	Boolean
isSetupComplete	Whether the user has completed your initial tax onboarding	Boolean

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

Field	Description	Format
useW2Withholding	Whether the user has specified their W-2 withholdings (allows for more accurate tax estimates); when not specified, Hurdlr estimates the W-2 withholding amount	Boolean
federalW2Withholding	Federal tax amount withheld from W-2 income; required if useW2Withholding is true	Numeric, with 2 decimal places
stateW2Withholding	State tax amount withheld from W-2 income; required if useW2Withholding is true	Numeric, with 2 decimal places
numExemptions	Number of state tax exemptions that the user qualifies for	Numeric
useHomeOfficeDeduction	Whether the user wants to use the simplified option for home office deduction	Boolean
homeOfficeArea	Size of the home office, in sq. feet (not to exceed 300)	Numeric, with 2 decimal places
useUserEstimatedRevenueForTaxCalc	Whether the user (or developer) wants to override Hurdlr's annual business income projection with their own estimate; this will impact annual and quarterly tax estimates	Boolean
userEstimatedAnnualRevenue	User's estimated annual business income	Numeric, 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.

1. Getting the user's tax profile

2. Updating the user's tax profile

📘Submitting Quarterly Tax Payments to the IRS

3. Displaying a tax disclaimer

📘
Submitting Quarterly Tax Payments to the IRS