Expense Category Report

Build a report with grouped transactions by category. Each category will have a sum and count of all transaction for this category from the respective account.

URL and Request Body Structure of a Expense Category Report

POST /insights/v1/reports/expense-category/create HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Token <Token>
Host: <Host>
{
    "insights_consumer_id": String,
    "insights_account_ids": ?Array<String>,
    "excluded_insights_account_ids": ?Array<String>,
    "report_days": ?Integer,
    "from_date": ?Date,
    "to_date": ?Date,
    "only_main_category" : ?Boolean,
    "split_by": ?Enum<'MONTH'>,
    "split_by_month_adjusted_day": ?Integer
}

insights_consumer_id String, required

The insights_consumer_id parameter identifies the consumer whose transactions are used to generate the report.

insights_account_ids String[], optional

The list of accounts, identified by the insights_account_id, which will filter all transactions from the consumer to only those accounts. If missing all accounts of the insights_consumer_id will be used to generate the report(s). The insights_account_ids parameter must be empty if the excluded_insights_account_ids parameter is set.

excluded_insights_account_ids String[], optional

The list of insights_account_ids which will be excluded from the report generation. The excluded_insights_account_ids parameter must be empty if the insights_account_ids parameter is set.

report_days Integer, optional

This parameter offers to provide a timeframe without need to calculate dates. If the report_days property is set, the parameters from_date and to_date will be derived from current day (today) minus the given number of days. The timeframe for which the report should be generated can be set by specifying either the from_date and to_date parameters or this report_days parameter. If no timeframe is specified, the default timeframe of the last 62 days will be used.

from_date Date (String: "YYYY-MM-DD"), optional

The from_date parameter (in combination with the to_date parameter) will be used as the inclusive start date for this timeframe. It has to be provided in the YYYY-MM-DD format according to ISO 8601.

The timeframe for which the report should be generated can be set by specifying either the from_date and to_date parameters or the report_days parameter. If no timeframe is specified, the default timeframe of the last 62 days will be used.

to_date Date (String: "YYYY-MM-DD"), optional

The to_date parameter (in combination with the from_date parameter) will be used as the inclusive end date for this timeframe. It has to be provided in the YYYY-MM-DD format according to ISO 8601.

The timeframe for which the report should be generated can be set by specifying either the from_date and to_date parameters or the report_days parameter. If no timeframe is specified, the default timeframe of the last 62 days will be used.

only_main_category boolean, optional

Since transactions can fit into multiple categories, this option tells the report to only consider the single best fitting category. The default for this flag is false.

split_by Enum, optional

Split each report into multiple reports depending on the requested timeframe and this parameter, resulting reports will be ordered ascending by timeframe.

For example: Setting this parameter to MONTH, from_date to 2021-01-01 and to_date to 2021-03-31 results in three reports, one for each month.

  • MONTH: Split by month, default start day of a month is the 1. That can be changed with split_by_month_adjusted_day.

split_by_month_adjusted_day integer, optional

Adjust the month start day. Valid values are 1-31, default is 1.

Response Structure of Expense Category Report

{
    "reports": Array<ExpenseReport>
}

reports ExpenseReport[], always present

The list of reports generated depending to the requested parameters.

Expense Report

{
    "type": "EXPENSE_CATEGORIES",
    "insights_consumer_id": String,
    "insights_account_ids": Array<String>,
    "categories": Array<CategoryInfo>,
    "from_date": Date,
    "to_date": Date,
    "refreshed_at": DateTime,
    "total_amount_sum": Amount,
    "split_by_month": ?Month
}

type String, always present

The type always contains the value "EXPENSE_CATEGORIES" for this report.

insights_consumer_id String, always present

The insights_consumer_id is the consumer identifier for the account(s) used in this report.

insights_account_ids String, always present

The insights_account_ids is used to identify a specific account within Account Insights. Depending on type of report and requested account-settings this could be a list of ids.

categories CategoryInfo[], always present

List of all category found for the account with count and sum of the corresponding transactions.

from_date Date (String: "YYYY-MM-DD"), always present

The starting date used to generate this report.

to_date Date (String: "YYYY-MM-DD"), always present

The end date used to generate this report.

refreshed_at DateTime, always present

The refreshed_at shows when the data for this account were last refreshed. It is provided in the YYYY-MM-DDThh:mm:ss.sssZ format according to ISO 8601 with an UTC offset, such as 2007-12-03T10:15:30.152Z.

total_amount_sum Amount, always present

The total amount of expenses. This is the the sum of all categories.amount_sum-values.

split_by_month Month, optional

The month this report represents. Is only returned if split_by is set to MONTH. It is provided in the YYYY-MM format according to ISO 8601.

CategoryInfo

{
    "id": String,
    "name": String,
    "count": Integer,
    "amount_sum": Amount,
    "amount_percentage": Double
}

id String, always present

The unique identifier of the category. Further details about a category will be provided by the Category List call.

name String, always present

Name of the category.

count Integer, always present

The number of transactions fitting this category.

amount_sum Amount, always present

The sum of all transactions corresponding to this category.

amount_percentage Double, always present

The percentage of the amount this category has compared to all other categories. All percentages combined may not add up to exactly 100% but slightly lower/higher because of rounding and the inexact representation of floating point numbers.

Example request

{
    "insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
    "report_days": 30,
    "only_main_category": true
}

Example response

{
    "data": {
        "reports": [
            {
                "type": "EXPENSE_CATEGORIES",
                "insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
                "insights_account_ids": [
                        "3b3d678f-66b7-4b23-a2a5-0bfd275e86a1"
                    ],
                "refreshed_at": "2021-06-15T09:22:01+0200",
                "total_amount_sum": {
                    "amount": 15965,
                    "currency": "EUR"
                },
                "categories": [
                    {
                        "id": "8f1f56e6-a312-454d-b0ee-e20350cb5c1c",
                        "name": "Bank charges",
                        "count": 4,
                        "amount_sum": {
                            "amount": 1438,
                            "currency": "EUR"
                        },
                        "amount_percentage": 9.0072033
                    },
                    {
                        "id": "0723e731-132d-4f00-a655-d9768dddc9b3",
                        "name": "Health insurance",
                        "count": 1,
                        "amount_sum": {
                            "amount": 14527,
                            "currency": "EUR"
                        },
                        "amount_percentage": 90.9927967
                    }
                ],
                "from_date": "2021-05-21",
                "to_date": "2021-06-14"
            }
        ]
    }
}

Example request with splitBy

{
    "insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
    "insights_account_ids": [
        "3b3d678f-66b7-4b23-a2a5-0bfd275e86a1", 
        "d111084f-04ef-4808-9455-939a7694c3be"
    ],
    "from_date": "2021-01-01",
    "to_date": "2021-02-28",
    "split_by": "MONTH"
}

Example response with splitBy

{
    "data": {
        "reports": [
            {
                "type": "EXPENSE_CATEGORIES",
                "insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
                "insights_account_ids": [
                        "3b3d678f-66b7-4b23-a2a5-0bfd275e86a1"
                    ],
                "refreshed_at": "2021-03-1T09:22:01+0200",
                "total_amount_sum": {
                    "amount": 1438,
                    "currency": "EUR"
                },
                "categories": [
                    {
                        "id": "8f1f56e6-a312-454d-b0ee-e20350cb5c1c",
                        "name": "Bank charges",
                        "count": 4,
                        "amount_sum": {
                            "amount": 1438,
                            "currency": "EUR"
                        },
                        "amount_percentage": 100.0
                    }
                ],
                "from_date": "2021-01-01",
                "to_date": "2021-01-31",
                "split_by_month": "2021-01"
            },
            {
                "type": "EXPENSE_CATEGORIES",
                "insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
                "insights_account_ids": [
                        "3b3d678f-66b7-4b23-a2a5-0bfd275e86a1"
                    ],
                "refreshed_at": "2021-03-1T09:22:01+0200",
                "total_amount_sum": {
                    "amount": 14527,
                    "currency": "EUR"
                },
                "categories": [
                    {
                        "id": "0723e731-132d-4f00-a655-d9768dddc9b3",
                        "name": "Health insurance",
                        "count": 1,
                        "amount_sum": {
                            "amount": 14527,
                            "currency": "EUR"
                        },
                        "amount_percentage": 100.0
                    }
                ],
                "from_date": "2021-02-01",
                "to_date": "2021-02-28",
                "split_by_month": "2021-02"
            },
            {
                "type": "EXPENSE_CATEGORIES",
                "insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
                "insights_account_ids": [
                        "d111084f-04ef-4808-9455-939a7694c3be"
                    ],
                "refreshed_at": "2021-03-1T09:22:01+0200",
                "total_amount_sum": {
                    "amount": 1438,
                    "currency": "EUR"
                },
                "categories": [
                    {
                        "id": "8f1f56e6-a312-454d-b0ee-e20350cb5c1c",
                        "name": "Bank charges",
                        "count": 4,
                        "amount_sum": {
                            "amount": 1438,
                            "currency": "EUR"
                        },
                        "amount_percentage": 100.0
                    }
                ],
                "from_date": "2021-01-01",
                "to_date": "2021-01-31",
                "split_by_month": "2021-01"
            },
            {
                "type": "EXPENSE_CATEGORIES",
                "insights_consumer_id": "6c03aff-8fa0046-ffae74-b0cbc-4d5fd1",
                "insights_account_ids": [
                        "d111084f-04ef-4808-9455-939a7694c3be"
                    ],
                "refreshed_at": "2021-03-1T09:22:01+0200",
                "total_amount_sum": {
                    "amount": 456789,
                    "currency": "EUR"
                },
                "categories": [
                    {
                        "id": "0723e731-132d-4f00-a655-d9768dddc9b3",
                        "name": "Groceries",
                        "count": 3,
                        "amount_sum": {
                            "amount": 456789,
                            "currency": "EUR"
                        },
                        "amount_percentage": 100.0
                    }
                ],
                "from_date": "2021-02-01",
                "to_date": "2021-02-28",
                "split_by_month": "2021-02"
            }
        ]
    }
}

results matching ""

    No results matching ""