Data Sources
Hurdlr's Income Streams API sits directly on top of your Plaid or MX integration. If you don't have an integration yet, Hurdlr enables you to skip past the burden of building your own back-end to store all that transaction (and related) data. Or, if you already have an integration, you can leverage Hurdlr's Income Streams API to enrich the data you're already storing.
Once you have your data source integration interfaced with the Hurdlr API (less than one calendar day of labor), you can immediately start using all of Hurdlr's Income Streams functionality.
1. Connecting your Plaid or MX integration
Please reference our Plaid integration or MX integration documentation for detailed instructions on connecting your data sources with the Hurdlr API.
2. Getting the user's revenues
Once you have successfully connected your data sources with the Hurdlr API, you can retrieve a list of the user's revenues. Be sure to include the user's access_token
in the headers.
curl \
--request GET \
--url https://sandbox.hurdlr.com/rest/v5/revenue/revenues?lastUpdatedDate=1970-01-01 \
--header 'Authorization: Bearer ${access_token}' \
--header 'Content-Type: application/json' \
lastUpdatedDate
On any given endpoint, if you populate the
lastUpdatedDate
URI parameter, the Hurdlr API will only return the records that have been updated since that date/time. Since users often have many transactions, to optimize performance we recommend settinglastUpdatedDate
to the last time that you initiated the same GET request; if this is your first request on behalf of a given user, simply pass in "1970-01-01". The response will contain alastUpdatedDate
, which we recommend you store in your DB, so that you can use that as an input parameter on your subsequent requests.
The response from GET /revenues contains an array of the user's revenues:
{
"data": [
{
"id": 172,
"type": "PENDING",
"date": "2021-08-30T20:58:19.000Z",
"amount": 399.99,
"businessId": null,
"clientId": null,
"description": "",
"bankDescription": "DEP CASH / CA 8665761039 BILL TANNER",
"apiInstitutionId": "ins_5",
"apiAccountName": "Citi Business Checking",
"apiAccountNo": "3333",
"apiName": "PLAID",
"apiPaymentId": "Broro8rVMMUmXAdw59mvsm909M547gtxRk34B",
"plaidItemAccountId": "17331",
"lastUpdatedDate": "2021-08-31T16:31:07.000Z",
}
],
"lastUpdatedDate": "2021-09-01T15:37:40.107Z"
}
On each revenue, you may find the following attributes to be of particular interest:
Field | Description | Format |
---|---|---|
id | Id of the revenue record | Numeric |
type | Type of revenue | Must be one of the following: "PENDING", "BUSINESS", "NOT_BUSINESS" |
date | Date that the revenue was deposited | yyyy-MM-dd'T'HH:mm:ss.SSSZ |
amount | Total value of the deposit | Numeric, with 2 decimal places |
lastUpdatedDate | Last date/time that this record was modified | yyyy-MM-dd'T'HH:mm:ss.SSSZ |
Additionally, several attributes to help you or your user identify a bank transaction are listed below:
Field | Description | Format |
---|---|---|
bankDescription | Transaction description (similar to what will show on the user's bank statement) | Any string |
apiInstitutionId | Id of the institution that the transaction originated from | Any string |
apiAccountName | Display name for the user's bank account | Any string |
apiAccountNo | Mask of the user's bank account, often the last 4 digits of the account number | 2-4 Alphanumeric characters |
plaidItemAccountId | Id of the bank account that this transaction originated from (within Hurdlr's API) | Numeric |
apiName | Name of the API that this transaction originated from | Will always be "PLAID", unless you are utilizing one of Hurdlr's other direct integrations |
apiPaymentId | Id of the transaction record in Plaid's API | Any string |
3. Classifying income transactions
Pending revenues, i.e. revenues with type == "PENDING"
, are income transactions that your user has not yet approved. Once they have been approved, they will be included in all the tax estimates, financial reporting, and other features that the Hurdlr API offers.
You should update the following fields on a revenue object when approving a pending revenue:
Field | Description | Format |
---|---|---|
id | Id of the existing pending revenue record | Numeric |
type | Whether the transaction is being classified as Business or Not Business | Must be one of the following: "BUSINESS", "NOT_BUSINESS" |
businessId | Id of the business that this should be assigned to (only used if status=BUSINESS) | Numeric |
clientId | Id of the client that this should be assigned to (only used if status=BUSINESS). Optional. | Numeric |
description | User-entered description of the income. Optional. | Any string |
To approve the pending revenue, simply POST the updated revenue's JSON object to the /revenue endpoint:
curl \
--request POST \
--url https://sandbox.hurdlr.com/rest/v5/revenue/revenue \
--header 'Authorization: Bearer ${access_token}' \
--header 'Content-Type: application/json' \
--data '{
"revenue": {
"id": 172,
"type": "BUSINESS",
"businessId": 416080,
"clientId": 805609,
"date": "2021-08-30T20:58:19.000Z",
"amount": 399.99,
"description": "Payment for design work"
}
}'
Of course, users can make mistakes or change their mind, and the Hurdlr API makes it easy for you to allow those updates. To update a classified income transaction, simply update the income's JSON object again as needed, and POST it to the /revenue endpoint like we did above.
Updated over 1 year ago