Investment Income
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 Hurdlr's Income Streams API has you covered.
1. How it works
The Hurdlr 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 Hurdlr API to ingest your user's investment income data, you can simply push each investment, or each type of investment, to the Hurdlr API. The Hurdlr API will take care of the rest.
Once you have your user's investment income pushed into the Hurdlr API (less than one calendar day of labor), you can immediately start using all of Hurdlr's Tax Calculations, Financial Statements, and other functionality.
2. Adding investment income
Investment income should be categorized using the following types:
Value | Use 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 Hurdlr 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 Hurdlr API.
You should update the following fields for any new or existing investment (or investment group):
Field | Description | Format |
---|---|---|
date | Date that the income was recognized on | yyyy-MM-dd or yyyy-MM-dd'T'HH:mm:ss.SSSZ |
amount | Total gain/loss (in dollars), for the given investment | Numeric, up to two decimal places (e.g. -1122.51 ) |
type | Income type, as defined in the table above | Must 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" |
description | Description 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 Hurdlr 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.
Updated 6 months ago