Tax Estimates

Once you've set up your user's tax profile and income streams, you can easily pull the users tax estimates from the Hurdlr API. As any of your user's data changes, so too will their tax estimates, in real-time.

1. Getting the user's tax estimates

First, you should retrieve the user's tax estimates. This endpoint has a period URL parameter, which must be one of the following values:

Value	Use Case
ANNUAL_PROJECTED	Projecting taxes for the current year. Especially useful for self-employed / business owners, since they are required to make estimated quarterly tax payments.
YTD	Showing the taxes owed based on income/expenses tracked thus far in the year. Useful if you are handling income/expense projections on your end and want to bypass Hurdlr's projections, or if you want to show your user a rolling tax obligation as opposed to a future projection.
LAST_YEAR	Pulling tax estimates for the prior year. Especially useful when the tax filing deadline is approaching (e.g. in April 2022, the user is paying taxes for 2021).

When making the GET request, be sure to include that user's access_token in the headers:

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

The response from GET /estimates contains a JSON object, with a vast amount of useful tax information:

{
  "country": "USA",
  "state": "DC",
  "year": 2022,
  "federalFilingStatus": "MS",
  "stateFilingStatus": "MS",
  "w2Income": 30000.00,
  "businessIncome": 102097.90,
  "expenses": 15314.69,
  "deductibleMileageExpenses": 0.00,
  "deductibleNonMileageExpenses": 15314.69,
  "homeOfficeDeduction": 0.00,
  "selfEmploymentDeduction": 6131.04,
  "adjustedGrossIncome": 110652.17,
  "overallTax": 25063.54,
  "overallTaxSavings": 35956.80,
  "overallTaxUnpaid": 25063.54,
  "federalTaxUnpaid": 19324.86,
  "stateTaxUnpaid": 5738.68,
  "annualPaymentDueDate": "2023-04-15 00:00:00.000",
  "afterTaxIncome": 91719.67,
  "otherIncome": 0.00,
  "federalTax": {
    "w2MarginalTaxRate": 12.00,
    "businessMarginalTaxRate": 22.00,
    "adjustedGrossIncome": 110652.17,
    "businessIncomeDeduction": 16130.43,
    "businessIncomeDeductionEffectiveRate": 20.00,
    "federalDeduction": 12950.00,
    "taxableIncome": 81571.74,
    "federalEffectiveTaxRate": 14.79,
    "federalTaxAmount": 12062.78,
    "medicareSurtax": {
      "investmentIncomeMedicareSurtax": 0.00,
      "earnedIncomeMedicareSurtax": 0.00
    },
    "selfEmploymentTax": {
      "socialSecurityTaxableIncome": 80144.29,
      "socialSecurityEffectiveTaxRate": 12.40,
      "socialSecurityTax": 9937.89,
      "medicareTaxableIncome": 80144.29,
      "medicareEffectiveTaxRate": 2.90,
      "medicareTax": 2324.18,
      "taxAmount": 12262.08
    },
    "taxBeforeWithholding": 24324.86,
    "effectiveTaxRateBeforeWithholding": 29.82,
    "withholdingAppliedToTax": 5000.00,
    "taxAmount": 19324.86,
    "effectiveTaxRate": 23.69,
    "employmentTax": {
      "socialSecurityTaxableIncome": 30000.00,
      "socialSecurityEffectiveTaxRate": 6.20,
      "socialSecurityTax": 1860.00,
      "medicareTaxableIncome": 30000.00,
      "medicareEffectiveTaxRate": 1.45,
      "medicareTax": 435.00,
      "taxAmount": 2295.00,
      "note": "The employmentTax numbers in this object are not used in the total federal calculations since the individual's tax filing will not include employment tax."
    }
  },
  "stateTax": {
    "w2MarginalTaxRate": 6.00,
    "businessMarginalTaxRate": 8.50,
    "adjustedGrossIncome": 110652.17,
    "stateDeduction": 12550.00,
    "taxableIncome": 98102.17,
    "preCreditEffectiveTaxRate": 6.87,
    "taxAmountWithoutTaxCredit": 6738.68,
    "taxCredit": 0.00,
    "otherTaxes": 0.00,
    "taxBeforeWithholding": 6738.68,
    "effectiveTaxRateBeforeWithholding": 6.87,
    "withholdingAppliedToTax": 1000.00,
    "taxAmount": 5738.68,
    "effectiveTaxRate": 5.85
  },
  "quarterlyEstimates": {
    "q1": {
      "dueDate": "2022-04-18 00:00:00.000",
      "federalTax": {
        "taxOwed": 4831.21,
        "taxPaid": 0.00,
        "paymentsAllocatedFromPast": 0.00,
        "paymentsRolledOverToFuture": false,
        "paymentsBalance": 4831.21
      },
      "stateTax": {
        "taxOwed": 1434.67,
        "taxPaid": 0.00,
        "paymentsAllocatedFromPast": 0.00,
        "paymentsRolledOverToFuture": false,
        "paymentsBalance": 1434.67
      }
    },
    "q2": {
      "dueDate": "2022-06-15 00:00:00.000",
      "federalTax": {
        "taxOwed": 3221.45,
        "taxPaid": 0.00,
        "paymentsAllocatedFromPast": 0.00,
        "paymentsRolledOverToFuture": false,
        "paymentsBalance": 3221.45
      },
      "stateTax": {
        "taxOwed": 956.64,
        "taxPaid": 0.00,
        "paymentsAllocatedFromPast": 0.00,
        "paymentsRolledOverToFuture": false,
        "paymentsBalance": 956.64
      }
    },
    "q3": {
      "dueDate": "2022-09-17 00:00:00.000",
      "federalTax": {
        "taxOwed": 4831.21,
        "taxPaid": 0.00,
        "paymentsAllocatedFromPast": 0.00,
        "paymentsRolledOverToFuture": false,
        "paymentsBalance": 4831.21
      },
      "stateTax": {
        "taxOwed": 1434.67,
        "taxPaid": 0.00,
        "paymentsAllocatedFromPast": 0.00,
        "paymentsRolledOverToFuture": false,
        "paymentsBalance": 1434.67
      }
    },
    "q4": {
      "dueDate": "2023-01-15 00:00:00.000",
      "federalTax": {
        "taxOwed": 6440.99,
        "taxPaid": 0.00,
        "paymentsAllocatedFromPast": 0.00,
        "paymentsRolledOverToFuture": false,
        "paymentsBalance": 6440.99
      },
      "stateTax": {
        "taxOwed": 1912.70,
        "taxPaid": 0.00,
        "paymentsAllocatedFromPast": 0.00,
        "paymentsRolledOverToFuture": false,
        "paymentsBalance": 1912.70
      }
    }
  }
}

2. Deciding what information to display

The art of building great FinTech apps includes figuring out how to display complex financial data in a way that a given user base can easily digest it. Hurdlr has iterated its tax UX through its own apps, with over 30 versions displayed to 700k+ users. Our team is willing and excited to share our proven UX learnings with you, fast forwarding you through your iteration process and ensuring that your first tax UX is a solid one.

Reach out to our API team at [email protected], and our team will advise you on which attributes to display and how to do so clearly/concisely.