Skip to main content
Certain types of investment income are often taxed differently than ordinary income, both at the federal and state level. If you are looking to provide better tax-related guidance to clients whose wealth you manage, or if you’re simply looking to provide more accurate tax estimates based on your user’s complex income situation, then Tight’s Income Streams API has you covered.

​
1. How it works

The Tight API is able to ingest data from many different income streams, enabling you to easily provide your users with accurate tax calculations, financial reporting, and other accounting functionality. In order for the Tight API to ingest your user’s investment income data, you can simply push each investment, or each type of investment, to the Tight API. The Tight API will take care of the rest. Once you have your user’s investment income pushed into the Tight API (less than one calendar day of labor), you can immediately start using all of Tight’s Tax Calculations, Financial Statements, and other functionality.

​
2. Adding investment income

Investment income should be categorized using the following types:
ValueUse Case
FEDERAL_OR_TERRITORIES_INTEREST
LONG_TERM_CAPITAL_GAIN
NON_QUALIFIED_DIVIDEND
OTHER_INTEREST
QUALIFIED_DIVIDEND
SHORT_TERM_CAPITAL_GAIN
SOCIAL_SECURITY_BENEFIT
TAX_FREE_INTEREST_OTHER_STATE
When pushing investment data into the Tight API, it is your choice as to whether you aggregate investments into each of the above types and POST data once per type or send each individual investment to the Tight API. You should update the following fields for any new or existing investment (or investment group):
FieldDescriptionFormat
dateDate that the income was recognized onyyyy-MM-dd or yyyy-MM-dd'T'HH:mm:ss.SSSZ
amountTotal gain/loss (in dollars), for the given investmentNumeric, up to two decimal places (e.g. -1122.51)
typeIncome type, as defined in the table aboveMust be one of the following: “FEDERAL_OR_TERRITORIES_INTEREST”, “LONG_TERM_CAPITAL_GAIN”, “NON_QUALIFIED_DIVIDEND”, “OTHER_INTEREST”, “QUALIFIED_DIVIDEND”, “SHORT_TERM_CAPITAL_GAIN”, “SOCIAL_SECURITY_BENEFIT”, “TAX_FREE_INTEREST_OTHER_STATE”
descriptionDescription of the income. Optional.Any string
To add or update an investment (or investment group), simply POST the investment’s JSON object to the /income endpoint: 
curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/investments/income \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
  "income": {
      "date": "2021-08-30T20:58:19.000Z",
      "amount": 3000.00,
      "type": "SHORT_TERM_CAPITAL_GAIN"
    }
  }'

​
3. Managing investment income

Now that you’ve added investment income, you will likely find that your user’s investment income changes from time to time, so you will need a way to pull their existing investment income, so that you can make updates to it. You can retrieve a list of the user’s investment income by making the following GET call: 
curl \
  --request GET \
  --url https://sandbox.hurdlr.com/rest/v5/investments/incomes \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
The response from GET /incomes contains an array of the user’s investment income: 
{
  "data": [
    {
      "id": 175,
      "date": "2021-08-30T20:58:19.000Z",
      "amount": 3000.00,
      "type": "SHORT_TERM_CAPITAL_GAIN",
      "description": "",
      "status": "ACTIVE"
    }
  ],
  "lastUpdatedDate": "2021-09-01T15:37:40.107Z"
}
To update existing investment income, you can simply edit the data in that specific investment income’s JSON object, and POST that object to the /income endpoint as described in the Adding investment income section. To delete existing investment income, you can simply edit the status field in that specific investment income’s JSON object to “INACTIVE”, and POST that object to the /income endpoint as described in the Adding investment income section.

​
4. Next steps

Once you have pushed your user’s investment income into the Tight API, you are ready to start pulling tax estimates! If you’d like to run various investment/tax scenarios, you can simply manipulate the user’s investment income (and income types), and see how the user’s taxes are impacted.