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 \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \



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:

idId of the revenue recordNumeric
typeType of revenueMust be one of the following: "PENDING", "BUSINESS", "NOT_BUSINESS"
dateDate that the revenue was depositedyyyy-MM-dd'T'HH:mm:ss.SSSZ
amountTotal value of the depositNumeric, with 2 decimal places
lastUpdatedDateLast date/time that this record was modifiedyyyy-MM-dd'T'HH:mm:ss.SSSZ

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

bankDescriptionTransaction description (similar to what will show on the user's bank statement)Any string
apiInstitutionIdId of the institution that the transaction originated fromAny string
apiAccountNameDisplay name for the user's bank accountAny string
apiAccountNoMask of the user's bank account, often the last 4 digits of the account number2-4 Alphanumeric characters
plaidItemAccountIdId of the bank account that this transaction originated from (within Hurdlr's API)Numeric
apiNameName of the API that this transaction originated fromWill always be "PLAID", unless you are utilizing one of Hurdlr's other direct integrations
apiPaymentIdId of the transaction record in Plaid's APIAny 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:

idId of the existing pending revenue recordNumeric
typeWhether the transaction is being classified as Business or Not BusinessMust be one of the following: "BUSINESS", "NOT_BUSINESS"
businessIdId of the business that this should be assigned to (only used if status=BUSINESS)Numeric
clientIdId of the client that this should be assigned to (only used if status=BUSINESS). Optional.Numeric
descriptionUser-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 \
  --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.