Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tight.com/llms.txt

Use this file to discover all available pages before exploring further.

Once you’ve set up your user’s tax profile and income streams, you can easily pull the users tax estimates from the Tight 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:
ValueUse Case
ANNUAL_PROJECTEDProjecting taxes for the current year. Especially useful for self-employed / business owners, since they are required to make estimated quarterly tax payments.
YTDShowing 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 Tight’s projections, or if you want to show your user a rolling tax obligation as opposed to a future projection.
LAST_YEARPulling 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. Tight 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 api@tight.com, and our team will advise you on which attributes to display and how to do so clearly/concisely.