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:
Field | Description | Format |
---|---|---|
id | Id of the personal category record | Numeric |
name | Name of the personal expense category | String |
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:
Field | Description | Format |
---|---|---|
id | Id of the expense record | Numeric |
type | Whether the transaction is being classified as Business or Not Business | Must be one of the following: "BUSINESS", "NOT_BUSINESS" |
personalCategoryId | Id of the personal expense category | Numeric |
description | User-entered description of the expense. Optional. | Any string |
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:
Field | Description | Format |
---|---|---|
date | Date that the expense was incurred | yyyy-MM-dd or yyyy-MM-dd'T'HH:mm:ss.SSSZ |
totalCost | Total cost of the expense | Numeric, with 2 decimal places |
type | Whether the transaction was classified as Business or Not Business | Must be one of the following: "BUSINESS", "NOT_BUSINESS" |
personalCategoryId | Id of the personal expense category | Numeric |
description | Description of the income. Optional. | Any string |
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.
Updated about 2 years ago