Introduction to Spending

Get an overview of your customers' regular and irregular expenses.

What it solves

To get to know the customer, it is important to know what their preferences are. This can be done with the Spending Report. In this report, all expenses are read out and categorized. This makes it possible to conclude, among other things, the customer’s lifestyle, which things he prefers, and on what he spends a lot or little money.

Spending Report

The spending report is based on the label SPENDINGREPORT and its further sub-labels with a higher level of detail.

The report gives an overview of data such as the number of relevant transactions. What types of spending are there? How frequent and how high is the spending?

Other data includes the account information and the transactions used in the report. This is very helpful if you want to check the values, for example, as part of a detailed credit check.

In addition, further reports can be created based on an initial report. These continuous reports can then be provided with triggers that always compare the values of the previous report with the current one and look for defined changes.

This is useful if you have access to the client's account data over a longer period of time.

It is important that not only days but ideally months are considered.

Aggregations

A Spending Report with monthly sections can be generated as an Aggregation with the following query:

JSON

{
  "aggregations": [
    {
      "alias": "Rent and Living",
      "includeLabelGroup": [ "RENT_AND_LIVING" ]
    },
    {
      "alias": "Insurances",
      "includeLabelGroup": [ "INSURANCE" ]
    },
    {
      "alias": "Savings",
      "includeLabelGroup": [ "SAVINGS" ]
    },
    {
      "alias": "Travel",
      "includeLabelGroup": [ "TRAVEL" ]
    },
    {
      "alias": "Tax",
      "includeLabelGroup": [ "TAX" ]
    },
    {
      "alias": "Bank and Credit",
      "includeLabelGroup": [ "BANKING" ]
    },
    {
      "alias": "Loan and Interest",
      "includeLabelGroup": [ "LOANANDINTEREST" ]
    },
    {
      "alias": "Mobility",
      "includeLabelGroup": [ "MOBILITY" ]
    },
    {
      "alias": "Shopping",
      "includeLabelGroup": [ "SHOPPING" ]
    },
    {
      "alias": "Entertainment",
      "includeLabelGroup": [ "ENTERTAINMENT" ]
    },
    {
      "alias": "Health and Wellness",
      "includeLabelGroup": [ "HEALTHANDWELLNESS" ]
    },
    {
      "alias": "Children",
      "includeLabelGroup": [ "CHILDREN" ]
    },
    {
      "alias": "Personnel Costs",
      "includeLabelGroup": [ "PERSONNEL_COST" ],
      "excludeLabelGroup": [ "TRAVEL_EXPENSES" ]
    },
    {
      "alias": "Travel Expenses",
      "includeLabelGroup": [ "TRAVEL_EXPENSES" ]
    },
    {
      "alias": "Legal Expenses",
      "includeLabelGroup": [ "LEGAL" ]
    },
    {
      "alias": "Billings",
      "includeLabelGroup": [ "BILLING" ]
    },
    {
      "alias": "Rebookings",
      "includeLabelGroup": [
        "REBOOKING_SPENDING",
        "PRIVATE_WITHDRAWAL_SPENDING",
        "PRIVATE_DEPOSIT_SPENDING"
      ]
    }
  ]
}

Used data fields

Spending transactions of the customer are used for this purpose. This includes data like IBAN, account holder name, counterpart name, purpose, amount, and so on.

The report response itself is divided into the following sections.

Main Section

The main part of the report can be found at $.reports.spending and the type will be SPENDING.

This gives you a quick overview of the transactions used in the report through aggregated values that can serve as a summary.

A full API schema can be seen here: https://docs.finapi.io/?product=di#get-/cases/-caseId-/reports

Field	Description	Mandatory
`creationDate`	Timestamp of when the report was created, in the format '`YYYY-MM-DD HH:MM:SS.SSS`' (CET Europe / Berlin).	yes
`caseId`	ID of the case in which the report was created.	yes
`type`	Defines the type of the report.	yes
`startDate`	Timestamp of the start date of the reporting period under review in the format '`YYYY-MM-DD HH:MM:SS.SSS`' (CET Europe / Berlin).	no
`endDate`	Timestamp of the end date of the reporting period under review in the format '`YYYY-MM-DD HH:MM:SS.SSS`' (CET Europe / Berlin)	no
`daysOfReport`	The number of full days, that the reporting period under review contains.	no
`transactionsStartDate`	Timestamp of the date, when user's first transaction took place in the report period under review in the format '`YYYY-MM-DD HH:MM:SS.SSS`' (CET Europe / Berlin). This field takes into consideration all the transactions of the user, irrespectively of the assigned to them label.	no
`totalTransactionsCount`	The number of the user transactions, that took place in the report period under review. This field takes into consideration all the transactions of the user, irrespectively of the assigned to them label.	no
`countIncomeTransactions`	The total count of positive transactions in the report.	yes
`countSpendingTransactions`	The total count of negative transactions in the report.	yes
`totalIncome`	The total income.	yes
`totalSpending`	The total spending.	yes
`totalBalance`	The total balance.	yes
`accountData`	List of accounts-related data with the relevant transactions information.	no
`childReports`	List of reports, created automatically with the specified frequency (defined by `interval` and `intervalPeriod`) once the parent report is defined as a continuous one.	no

Account Data Section

The account data section can be found under the accountData field.
It contains data about the account at the first level.
If more than one account is included in the report, they will be displayed individually in the list.

Field	Description	Mandatory
`bankName`	Name of the bank.	yes
`bankId`	Unique identifier of the Bank, generated by finAPI.	yes
`accountIban`	IBAN of the bank account.	no
`accountId`	Unique identifier of the bank account belonging to the imported bank connection.	no
`transactions`	List of transactions related to the chosen report type.	no

Transactions Section

This section displays the transactions used in the report and can be found under the accountData element in the field transactions.
Please note that this list may be very long, especially for business accounts.

Depending on what the report is used for, the transactions can be retrieved for later review or documentation, or they can be turned off. The latter would be the case, for example, if you only want to do a quick check of the overall data and do not need any details.

If transactions are not of interest, you can also disable this section by giving the query parameter withTransactions=false to the report.

The transactions include the following values.

Field	Description	Mandatory
`valueDate`	Value date in the format '`YYYY-MM-DD HH:MM:SS`' (CET Europe / Berlin).	yes
`bankBookingDate`	Bank booking date in the format '`YYYY-MM-DD HH:MM:SS`' (CET Europe / Berlin).	yes
`amount`	Transaction amount.	yes
`purpose`	Transaction purpose.	no
`counterpartName`	Counterpart name.	no
`counterpartAccountNumber`	Counterpart account number.	no
`counterpartIban`	Counterpart IBAN.	no
`counterpartBlz`	Counterpart BLZ.	no
`counterpartBic`	Counterpart BIC.	no
`counterpartBankName`	Counterpart bank name.	no
`labels`	A list of labels assigned by the system. This does not contain the complete label structure in the sense of level of detail.	no
`labelDetails`	Includes a much more detailed view of the labels including all level of detail and the most significant labels. To see this section, the report must be called with the query parameter `withLabelDetails=true`.	no
`overdraftInformation`	Extracted details for transactions with related to overdraft interests. It includes an object that contains fields such as the overdraft amount and the period of the overdraft.	no

Monthly Data (Aggregations)

Monthly Data are aggregations generated over the report period for specific sub-aspects of the report.
These are reported on a monthly basis and made available as a summary.

Field

Description

Mandatory

completeMonths

This field contains a list of months for which finAPI has complete records available. This automatically means that the first and the last month of the report period are omitted from the list.

no

monthlyData

Monthly aggregations of various data are listed under this field. These reflect the monthly development of certain criteria in the transactions.

The month, the value, and the number of transactions behind it are always indicated.

no

Subelements of Monthly Data

This section describes the subfields of the Monthly Data section that can appear in the report.

Additionally, aggregations are provided for the sections behind the subelement, which include values such as totalMonthlyAmounts, minTotalMonthlyAmount, maxTotalMonthlyAmount, averageTotalMonthlyAmount, and medianTotalMonthlyAmount.

Here we take into consideration the data from both complete and incomplete months inside the report period under review.

Field	Description	Mandatory
`totalSpending`	Spending data (for all the kinds of spending (`totalSpending`) or per particular category) organized by months.	yes
`rebookings`	Rebooking spending of the customer between 2 own or accessible accounts or private withdrawals. This part is only fully available if an extended analysis has been performed before. Transactions can be recognized as rebooking, but without the advanced analysis they represent only a fraction. To perform a full analysis, please use the endpoint `/extendedAnalyses/rebooking` for rebooking data.	no
`rentAndLiving`	Rent and living spending data, organized by months.	no
`insurance`	Insurance spending data, organized by months.	no
`bankAndCredit`	Bank and credit spending data, organized by months.	no
`loanAndInterest`	Loan and interest spending data, organized by months.	no
`savings`	Savings spending data, organized by months.	no
`travel`	Travel spending data, organized by months.	no
`tax`	Tax spending data, organized by months.	no
`mobility`	Mobility spending data, organized by months.	no
`shopping`	Shopping spending data, organized by months.	no
`entertainment`	Entertainment spending data, organized by months.	no
`healthAndWellness`	Health and wellness spending data, organized by months.	no
`children`	Children spending data, organized by months.	no
`personnelCosts`	Personnel costs for company accounts.	no
`travelExpenses`	Expenses for traveling by the employer for company accounts.	no
`legal`	Expenses, that are related to or in compliance with laws and legal regulations.	no
`billings`	Expenses, related to billings or material costs.	no

Label Details Section

To get more information about labels or the whole Level of Detail structure, this section can be enabled using the query parameter withLabelDetails=true.

This is particularly interesting if you want to perform your own evaluations based on the reports. You are able to select all transactions of a certain level of detail because the complete structure is available.

Field	Description	Mandatory
`labelsWithLevelOfDetails`	List of labels including their Level of Details structure.	yes
`labelsExpandedLowerLod`	List of labels including the level of details as a flat list.	yes
`mostSignificantLabels`	Most significant labels in the report context including its level of detail, depending on the priority of labels.	yes
`mostSignificantLod1`	Most significate label of level 1	no
`mostSignificantIncomeLod2`	Most significant income related label of level 2	no

Labels with Level of Details

The general part of the Label Details section is summarized in the labelsWithLevelOfDetails field.
This shows the complete structure for each label in a list.

For example, if a label with REALESTATELOAN was output in a transaction, this element returns the following structure for the label:

LoD 1: BANKANDCREDIT
LoD 2: LOANANDINTEREST
LoD 3: REALESTATELOAN

This allows to derive some more context and it allows to select for example LOANANDINTEREST in all issued transactions of the report, should one be interested only in such transactions.

Since labels may belong to several label groups (e.g. CARLOAN is both LOANANDINTEREST and MOBILITY), it is possible to identify which groups are involved.

Labels Expanded Lower Level of Details

In the field labelsExpandedLowerLod a simple list of all labels and their level of details is displayed. However, there is no order of the levels, but only all labels, including the levels below them, are displayed as text.

Therefore, this field is best suited for a simple one of a particular label group.

Most significant labels

The mostSignificantLabels field returns the most appropriate labels in the report context including its level of detail.

This is controlled by the priorities when the report is created.

For example, if a transaction has the label CARLOAN, it may appear in the level of detail 1 in the groups MOBILITY and BANKANDCREDIT.
However, by using the priorities, which map what you are most interested in, only one group is returned here.
For example, if the priority of BANKANDCREDIT is higher than that of MOBILITY, the structure of BANKANDCREDIT will be returned.

The reverse would be the MOBILITY group.

Most significant Level of Detail 1

This area is represented by the field mostSignificantLod1.

Only the most important label of level 1, is returned. This is the label that has the highest value in the level.

This is provided for the selection of transactions at level 1. The assumption is that a higher level of detail often results in more accurate, specialized recognition.

Most significant Level of Detail 2 for income transactions

If there are multiple labels in an incoming (positive) transaction, the most significant label is mapped here.
This is also based on the priorities, which can be set with the field incomeLevelOfDetail2Priority when creating the report.

As a result, the highest level of detail of the transaction is returned here, which can be an indicator that this is the most accurate context.