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:

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.