Personal Expenses

1. How it works

Through Hurdlr's Plaid integration, your user's transactions are pulled into Hurdlr as soon as Plaid makes them available. All of those transactions are then run through Hurdlr's proprietary algorithms, which leverage the user's business type, accountant best practices, and the behavior of similar businesses within the Hurdlr app's 700k+ users. One output of those algorithms is the assignment of personal expense categories.

If you are not using Hurdlr's expense integrations, in order for the Hurdlr API to ingest your user's non-business expense data, you can simply push each expense record, as they are incurred, to the Hurdlr API. The Hurdlr API will take care of the rest.

2. Getting the user's pending expenses

Once you have successfully set up the Plaid Integration with the Hurdlr API, you can retrieve a list of the user's pending expenses, which are expense transactions that your user has not yet approved.

3. Identifying a transaction's personal categorization

On each expense transaction, you will see a personalCategoryId field, which maps to one of Hurdlr's personal expense categories. To pull a user's personal expense categories, you can make the following GET call. Be sure to include that user's access_token in the headers.

curl \
  --request GET \
  --url https://sandbox.hurdlr.com/rest/v5/expenses/personalCategories?lastUpdatedDate=1970-01-01 \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \

The response from GET /personalCategories contains an array of the user's personal expense categories:

{
  "data": [
    {
      "id": 271884,
      "name": "Travel",
      "hasChilds": true,
      "parentCategoryId": null,
      "status": "ACTIVE",
      "lastUpdatedDate": "2021-10-11T15:36:24.000Z"
    },
    {
      "id": 271885,
      "name": "Airlines",
      "hasChilds": false,
      "parentCategoryId": 271884,
      "status": "ACTIVE",
      "lastUpdatedDate": "2021-10-11T15:36:24.000Z"
    },
    ...
  ],
  "lastUpdatedDate": "2021-10-11T15:38:57.908Z"
}

On each personal expense category, you may find the following attributes to be of particular interest:

4. Classifying personal expense transactions

Pending expenses, i.e. expenses with type == "PENDING", are expense transactions that your user has not 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 pending expense object when approving a pending expense:

To approve the pending expense, simply POST the updated expense's JSON object to the /expense endpoint:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/expenses/expense \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "pendingExpense": {
      "id": 1118496,
      "type": "NOT_BUSINESS",
      "date": "2020-08-27 00:00:00.000",
      "totalCost": 500.39,
      "personalCategoryId": 233391,
      "vendorId": 237791,
      "description": "Flight to visit college friends"
    }
  }'

5. Adding new personal expenses

For any other expenses from sources outside of the Plaid integration, you can simply add those expenses by making a POST call to the Hurdlr API.

You should update the following fields on a new JSON object when adding personal expenses:

To add the expense, simply POST the income's JSON object to the /expense endpoint:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v4/expenses/expense \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
  	"revenue": {
      "date": "2021-07-30",
      "totalCost": 500.00,
      "type": "NOT_BUSINESS",
      "personalCategoryId": 233391,
      "description": "Design implementation"
    }
  }'

6. Getting personal expenses

All business or non-business expenses can be accessed in the list of expenses, via the /expenses endpoint.