Budgets

>>>

GET /api/budgets
Show list of the budgets user- and company-specific

Returns list of the budgets of the user in the specific company

Supported Formats

json

Examples

[
  {
    "id": 1,
    "user_id": 1,
    "approver_id": 1,
    "name": "Travel Budget",
    "start_date": "28-11-2022",
    "end_date": "28-12-2022",
    "amount": "20.00",
    "amount_currency": "EUR",
    "used_amount": "15.00",
    "state": "approved",
    "lines": [
      {
        "id": 1,
        "amount": "10.00",
        "amount_currency": "EUR",
        "expense_account_id": 1
      },
      {
        "id": 2,
        "amount": "10.00",
        "amount_currency": "EUR",
        "expense_account_id": 1
      }
    ]
    "cost_centers": [
      {
        "id": 1,
        "dimension_name": "Project",
        "name": "Some project 1",
        "deactivated": false
      }
    ],
    "documents": [
      {
        "id": 1,
        "name": "agenda.pdf",
        "file": "https://example.com/agenda.pdf"
      }
    ]
  }
]

Params

Param name Description
page
optional

Page number

Validations:

  • Must be a Integer
per_page
optional

Number of records per page. Default: 30

Validations:

  • Must be a Integer
q
optional

Pass query to filter budgets by total amount or name.

Validations:

  • Must be a String
user_id
optional

Pass user_id to get budgets of that user.

Validations:

  • Must be a Integer
state
optional

Pass state to get budgets with that state.

Validations:

  • Must be one of: pending, approved, disapproved.
date_range
optional

Show all budgets that have either star_date or end_date within the date range. Date range format: “DD/MM/YYYY - DD/MM/YYYY” (example: 01/12/2023 - 12/12/2023)

Validations:

  • Must be a String
sort_by
optional

Return budgets sorted by following fields: user_name, state, start_date, end_date, approver_name. Default: approver_id.

Validations:

  • Must be a String
order
optional

Order budgets ascending or descending based on sort param. Default: asc

Validations:

  • Must be one of: asc, desc.
>>>

POST /api/budgets
Create budget

Create budget

Params

Param name Description
budget
required

Budget parameters.

Validations:

  • Must be a Hash
budget[name]
required

Budget name.

Validations:

  • Must be a String
budget[description]
optional

Budget description. Maximum length: 1500 characters.

Validations:

  • Must be a String
budget[start_date]
required

Budget’s start date, e.g. 2024-12-01. Must be in the future. Cannot overlap with existing budgets with the same user & expense account combination.

Validations:

  • Must be a String
budget[end_date]
required

Budget’s end date, e.g. 2024-12-31. Must be in the future. Cannot overlap with existing budgets with the same user & expense account combination.

Validations:

  • Must be a String
budget[cost_center_ids]
optional

Cost center IDs. No more than one cost center ID per dimension.

Validations:

  • Must be an array of Integer
budget[user_id]
optional

User ID. Current user ID by default. Only managers can create budgets on behalf of other users.

Validations:

  • Must be a Integer
budget[approver_id]
optional

ID of user who is to approve the budget. By default, user’s first approver will be used. If there is no approval cycle behind the user, company’s default approver will be used.

Validations:

  • Must be a Integer
budget[lines_attributes]
required

Budget lines’ parameters. At least one line must be present.

Validations:

  • Must be an Array of nested elements
budget[lines_attributes][amount]
required

Line amount as a decimal number, e.g. “123.55”.

Validations:

  • Must be a String
budget[lines_attributes][amount_currency]
optional

Amount currency, e.g. “EUR”. Set to company currency by default.

Validations:

  • Must be a String
budget[lines_attributes][expense_account_id]
required

Expense account (aka purchase type) for the budget line.

Validations:

  • Must be a Integer
>>>

PUT /api/budgets/:id
Update budget

Update budget. Approved budgets cannot be updated. Successful update of a disapproved budget returns it to pending state.

Params

Param name Description
id
required

Budget ID

Validations:

  • Must be a Integer
budget
required

Budget parameters.

Validations:

  • Must be a Hash
budget[name]
required

Budget name.

Validations:

  • Must be a String
budget[description]
optional

Budget description. Maximum length: 1500 characters.

Validations:

  • Must be a String
budget[start_date]
required

Budget’s start date, e.g. 2024-12-01. Must be in the future. Cannot overlap with existing budgets with the same user & expense account combination.

Validations:

  • Must be a String
budget[end_date]
required

Budget’s end date, e.g. 2024-12-31. Must be in the future. Cannot overlap with existing budgets with the same user & expense account combination.

Validations:

  • Must be a String
budget[cost_center_ids]
optional

Cost center IDs. No more than one cost center ID per dimension.

Validations:

  • Must be an array of Integer
budget[user_id]
optional

User ID. Current user ID by default. Only managers can create budgets on behalf of other users.

Validations:

  • Must be a Integer
budget[approver_id]
optional

ID of user who is to approve the budget. By default, user’s first approver will be used. If there is no approval cycle behind the user, company’s default approver will be used.

Validations:

  • Must be a Integer
budget[lines_attributes]
required

Budget lines’ parameters. At least one line must be present.

Validations:

  • Must be an Array of nested elements
budget[lines_attributes][amount]
required

Line amount as a decimal number, e.g. “123.55”.

Validations:

  • Must be a String
budget[lines_attributes][amount_currency]
optional

Amount currency, e.g. “EUR”. Set to company currency by default.

Validations:

  • Must be a String
budget[lines_attributes][expense_account_id]
required

Expense account (aka purchase type) for the budget line.

Validations:

  • Must be a Integer
>>>

DELETE /api/budgets/:id
Delete budget

Params

Param name Description
id
required

Budget ID

Validations:

  • Must be a Integer