Budgets

Budgets are a crucial tool in financial planning, helping you allocate resources, track expenses, and achieve financial goals. On this page, we’ll dive into the different budget endpoints you can use to manage budgets programmatically. We'll look at how to query, create, update, and delete budgets.

The budget model

The budget model contains all the information about your financial budgets. Each budget can include details about allocated amounts, spending categories, and tracking periods.

Properties

Name
id
Type
string
Description
Unique identifier for the budget.
Name
name
Type
string
Description
Name of the budget.
Name
total_amount
Type
number
Description
Total amount allocated for the budget.
Name
currency
Type
string
Description
Currency used in the budget.
Name
start_date
Type
date
Description
Start date of the budget period.
Name
end_date
Type
date
Description
End date of the budget period.
Name
created_at
Type
timestamp
Description
Timestamp of when the budget was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the budget was last updated.

GET/v1/budgets

List all budgets

This endpoint allows you to retrieve a paginated list of all your budgets. By default, a maximum of ten budgets are shown per page.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of budgets returned.
Name
start_date
Type
date
Description
Only show budgets starting from this date.
Name
end_date
Type
date
Description
Only show budgets ending on this date.

Request

GET

/v1/budgets

curl -G https://api.finx.ai/v1/budgets \
  -H "Authorization: Bearer {token}" \
  -d limit=10

Response

{
  "has_more": false,
  "data": [
    {
      "id": "xgQQXg3hrtjh7AvZ",
      "name": "Monthly Expenses",
      "total_amount": 2000,
      "currency": "USD",
      "start_date": "2024-01-01",
      "end_date": "2024-01-31",
      "created_at": 705103200,
      "updated_at": 705103200
    },
    {
      "id": "hSIhXBhNe8X1d8Et"
      // ...
    }
  ]
}

POST/v1/budgets

Create a budget

This endpoint allows you to add a new budget. You need to provide the budget name, total amount, currency, and the start and end dates to create a budget.

Required attributes

Name
name
Type
string
Description
Name of the budget.
Name
total_amount
Type
number
Description
Total amount allocated for the budget.
Name
currency
Type
string
Description
Currency used in the budget.
Name
start_date
Type
date
Description
Start date of the budget period.
Name
end_date
Type
date
Description
End date of the budget period.

Request

POST

/v1/budgets'

curl https://api.finx.ai/v1/budgets \
  -H "Authorization: Bearer {token}" \
  -d 'name'="Monthly Expenses" \
  -d 'total_amount'=2000 \
  -d 'currency'="USD" \
  -d 'start_date'="2024-01-01" \
  -d 'end_date'="2024-01-31"

Response

{
  "id": "xgQQXg3hrtjh7AvZ",
  "name": "Monthly Expenses",
  "total_amount": 2000,
  "currency": "USD",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "created_at": 705103200,
  "updated_at": 705103200
}

GET/v1/budgets/:id

Retrieve a budget

This endpoint allows you to retrieve a budget by providing the budget id. Refer to the list at the top of this page to see which properties are included with budget objects.

Request

GET

/v1/budgets/xgQQXg3hrtjh7AvZ

curl https://api.finx.ai/v1/budgets/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "xgQQXg3hrtjh7AvZ",
  "name": "Monthly Expenses",
  "total_amount": 2000,
  "currency": "USD",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "created_at": 705103200,
  "updated_at": 705103200
}

PUT/v1/budgets/:id

Update a budget

This endpoint allows you to perform an update on a budget. Examples of updates are changing the total amount, updating the currency, or modifying the budget period.

Optional attributes

Name
total_amount
Type
number
Description
Updated total amount allocated for the budget.
Name
currency
Type
string
Description
Updated currency used in the budget.
Name
start_date
Type
date
Description
Updated start date of the budget
period.
Name
end_date
Type
date
Description
Updated end date of the budget period.

Request

PUT

/v1/budgets/xgQQXg3hrtjh7AvZ

curl -X PUT https://api.finx.ai/v1/budgets/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}" \
  -d 'total_amount'=2500

Response

{
  "id": "xgQQXg3hrtjh7AvZ",
  "name": "Monthly Expenses",
  "total_amount": 2500,
  "currency": "USD",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "created_at": 705103200,
  "updated_at": 705103200
}

DELETE/v1/budgets/:id

Delete a budget

This endpoint allows you to delete your budgets in Fin X. Note: This will permanently delete the budget and all its data — ensure this is the desired action before proceeding.

Request

DELETE

/v1/budgets/xgQQXg3hrtjh7AvZ

curl -X DELETE https://api.finx.ai/v1/budgets/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}"