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": {
      "id": 4241,
      "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.