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 setting lastUpdatedDate 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 a lastUpdatedDate, 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:

Additionally, several attributes to help you or your user identify a bank transaction are listed below:

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:

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.