budgets

Purpose

The budgets route contains all endpoints related to the management of budgets.

get all

This endpoint is used to retrieve all budgets.

Request:
GET /api/v1/budgets/all

Response:

[
    {
        "id": "42d46365-1219-4a15-a536-4c2eca8e4bdf",
        "name": "technology",
        "user_id": "6b875d6c-7d4e-4ae3-931f-270604df1d7f",
        "amount": {
            "major": 123,
            "minor": 45,
            "minor_in_major": 100,
            "symbol": "€",
            "is_negative": false
        },
        "rollover": false,
        "period": 2,
        "filter_tag_ids": ["baf5ba00-440c-4d8a-a614-be2cbf4c2beb", "61d6ffc7-9d41-4d4d-ac0b-1c4fb92606eb"],
        "currency_id": "ffc53ce5-0bd2-4464-94b3-9866e506fd91",
        "active_from": "2023-01-01T10:10:00Z",
        "active_to": null,
        "used_amount": {
            "major": 10,
            "minor": 50,
            "minor_in_major": 100,
            "symbol": "€",
            "is_negative": false
        },
        "available_amount": {
            "major": 112,
            "minor": 95,
            "minor_in_major": 100,
            "symbol": "€",
            "is_negative": false
        },
        "utilization": 8.5054678007
    }
]

Property	Description	Type	Filterable	Sortable
id	the id of the budget	UUIDv4	Yes	No
name	the name of the budget	string	Yes	No
user_id	the id of the user owning this budget	UUIDv4	No	No
amount	the total amount set for the budget	Money	Yes	No
rollover	if unused budget is rolled over into the next period	boolean	Yes	No
period	how often the budget resets 0=daily, 1=weekly, 2=monthly, 3=quarterly, 4=yearly	number	No	No
filter_tag_ids	ids of the tags whose transactions get included in this budget	UUIDv4[]	Yes	No
currency_id	if of the currency used in this budget	UUIDv4	Yes	No
active_from	from which point in time onwards transactions should get included in this budget	timestamp	Yes	No
active_to	until which point in time transactions should get included in this budget	timestamp?	Yes	No
used_amount	amount of money spent in current period	Money?	No	No
available_amount	amount of money still available in current period	Money?	No	No
utilization	percentage of used money in current period	number?	No	No

get by id

This endpoint is used to retrieve a single budget by its id. You need to specify the id of the budget you want to retrieve in the request path.

Request:
GET /api/v1/budgets/{budget_id}

Response:

{
    "id": "42d46365-1219-4a15-a536-4c2eca8e4bdf",
    "name": "technology",
    "user_id": "6b875d6c-7d4e-4ae3-931f-270604df1d7f",
    "amount": {
        "major": 123,
        "minor": 45,
        "minor_in_major": 100,
        "symbol": "€",
        "is_negative": false
    },
    "rollover": false,
    "period": 2,
    "filter_tag_ids": ["baf5ba00-440c-4d8a-a614-be2cbf4c2beb", "61d6ffc7-9d41-4d4d-ac0b-1c4fb92606eb"],
    "currency_id": "ffc53ce5-0bd2-4464-94b3-9866e506fd91",
    "active_from": "2023-01-01T10:10:00Z",
    "active_to": null,
    "used_amount": {
        "major": 10,
        "minor": 50,
        "minor_in_major": 100,
        "symbol": "€",
        "is_negative": false
    },
    "available_amount": {
        "major": 112,
        "minor": 95,
        "minor_in_major": 100,
        "symbol": "€",
        "is_negative": false
    },
    "utilization": 8.5054678007
}

Property	Description	Type
id	the id of the budget	UUIDv4
name	the name of the budget	string
user_id	the id of the user owning this budget	UUIDv4
amount	the total amount set for the budget	Money
rollover	if unused budget is rolled over into the next period	boolean
period	how often the budget resets 0=daily, 1=weekly, 2=monthly, 3=quarterly, 4=yearly	number
filter_tag_ids	ids of the tags whose transactions get included in this budget	UUIDv4[]
currency_id	if of the currency used in this budget	UUIDv4
active_from	from which point in time onwards transactions should get included in this budget	timestamp
active_to	until which point in time transactions should get included in this budget	timestamp?
used_amount	amount of money spent in current period	Money?
available_amount	amount of money still available in current period	Money?
utilization	percentage of used money in current period	number?

get transactions

This endpoint is used to retrieve all transactions matching this budget in its current period.
You need to specify the id of the budget you want to retrieve transactions of in the request path.

Request:
GET /api/v1/budgets/{budget_id}/transactions

Response:

[
    {
        "id": "b0e4eb0c-3719-4da8-bedc-27ca238b6ebc",
        "user_id": "6b875d6c-7d4e-4ae3-931f-270604df1d7f",
        "currency_id": "ffc53ce5-0bd2-4464-94b3-9866e506fd91",
        "account_id": "525c32a8-c200-4c5d-a3c7-ef8936cc1c84",
        "recipient_id": "e3001fbc-1e28-44ad-94f6-9900be5dbc52",
        "status": 1,
        "timestamp": "2023-01-01T10:10:00Z",
        "total_amount": {
            "major": 10,
            "minor": 50,
            "minor_in_major": 100,
            "symbol": "€",
            "is_negative": false
        },
        "comment": "hello world!",
        "tag_ids": ["baf5ba00-440c-4d8a-a614-be2cbf4c2beb", "61d6ffc7-9d41-4d4d-ac0b-1c4fb92606eb"],
        "asset": null,
        "positions": [
            {
                "id": "0a02167e-9a47-41ad-90b1-936b17e3a6f1",
                "amount": {
                    "major": 10,
                    "minor": 50,
                    "minor_in_major": 100,
                    "symbol": "€",
                    "is_negative": false
                },
                "comment": "Im the only position!",
                "tag_id": "baf5ba00-440c-4d8a-a614-be2cbf4c2beb"
            }
        ]
    }
]

Property	Description	Type
id	the id of the transaction	UUIDv4
user_id	the id of the user owning this transaction	UUIDv4
currency_id	the id of the currency this transaction is using	UUIDv4?
account_id	the id of the account this transaction belongs to	UUIDv4
recipient_id	the id of the recipient this transaction belongs to	UUIDv4
status	the status of the transaction, will always be 1=completed	number
timestamp	the time when this transaction has taken place	timestamp
total_amount	the total amount of money of all positions combined	Money?
comment	an optional comment describing this transaction	string?
tag_ids	the ids of tags this transaction belongs to	UUIDv4[]
asset	the asset this transactions belongs to	Asset?
positions	the positions this transaction consists of	Position[]

create budget

This endpoint is used to create new budgets.

Request:
POST /api/v1/budgets

{
    "name": "technology",
    "amount": {
        "major": 123,
        "minor": 45,
        "minor_in_major": 100,
        "symbol": "€",
        "is_negative": false
    },
    "rollover": false,
    "period": 2,
    "filter_tag_ids": ["baf5ba00-440c-4d8a-a614-be2cbf4c2beb", "61d6ffc7-9d41-4d4d-ac0b-1c4fb92606eb"],
    "currency_id": "ffc53ce5-0bd2-4464-94b3-9866e506fd91",
    "active_from": "2023-01-01T10:10:00Z",
    "active_to": null,
}

Property	Description	Type
name	the name of the budget	string
amount	the total amount set for the budget	Money
rollover	if unused budget is rolled over into the next period	boolean
period	how often the budget resets 0=daily, 1=weekly, 2=monthly, 3=quarterly, 4=yearly	number
filter_tag_ids	ids of the tags whose transactions get included in this budget	UUIDv4[]
currency_id	if of the currency used in this budget	UUIDv4
active_from	from which point in time onwards transactions should get included in this budget	timestamp
active_to	until which point in time transactions should get included in this budget	timestamp?

Response:

{
    "id": "42d46365-1219-4a15-a536-4c2eca8e4bdf"
}

Property	Description	Type
id	the id of the newly created budget	UUIDv4

modify budget

This endpoint is used to modify an existing budget.
You need to specify the id of the budget you want to modify in the request path.

Request:
PUT /api/v1/budget/{budget_id}

{
    "name": "technology",
    "amount": {
        "major": 123,
        "minor": 45,
        "minor_in_major": 100,
        "symbol": "€",
        "is_negative": false
    },
    "rollover": false,
    "period": 2,
    "filter_tag_ids": ["baf5ba00-440c-4d8a-a614-be2cbf4c2beb", "61d6ffc7-9d41-4d4d-ac0b-1c4fb92606eb"],
    "currency_id": "ffc53ce5-0bd2-4464-94b3-9866e506fd91",
    "active_from": "2023-01-01T10:10:00Z",
    "active_to": null,
}

Property	Description	Type
name	the name of the budget	string
amount	the total amount set for the budget	Money
rollover	if unused budget is rolled over into the next period	boolean
period	how often the budget resets 0=daily, 1=weekly, 2=monthly, 3=quarterly, 4=yearly	number
filter_tag_ids	ids of the tags whose transactions get included in this budget	UUIDv4[]
currency_id	if of the currency used in this budget	UUIDv4
active_from	from which point in time onwards transactions should get included in this budget	timestamp
active_to	until which point in time transactions should get included in this budget	timestamp?

delete budget

This endpoint is used to delete an existing budget. You need to specify the id of the budget you want to delete in the request path.

Request:
DELETE /api/v1/budgets/{budget_id}