Introduction to Income

Gain insights into all the different types of income your customers generate.

This report is appropriate for B2B and B2C use cases.

What it solves

The Income Report shows all incoming transactions and all sources of income identified through labeling.

For optimal cooperation with a client, it is important to have an accurate insight into what types of income they have. In the past, the client has had to enter his income himself via a self-report, which can lead to errors. With the Income Report, all income is read directly from the account and structured by type. This allows an informed decision to be made and saves time.

Income Report

The income report is based on the label INCOME 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 income are there? How frequent and how high is this income?

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

An Income Report can be generated as an Aggregation with the following query:

JSON

{
  "aggregations": [
    {
      "alias": "Income",
      "includeLabelGroup": [
        "INCOME"
      ],
      "excludeLabelGroup": [
        "PAYMENT_PROCESSING", "PRIVATE_DEPOSIT_INCOME"
      ]
    }
  ]
}

Or create relevant income monthly views with this query:

JSON

{
  "aggregations": [
    {
      "alias": "Salary",
      "includeLabelGroup": [ "SALARY" ]
    },
    {
      "alias": "Captial Income",
      "includeLabelGroup": [ "CAPITALINCOME" ]
    },
    {
      "alias": "Rental Income",
      "includeLabelGroup": [ "RENTALINCOME" ]
    },
    {
      "alias": "Pension and Retirement",
      "includeLabelGroup": [ "PENSIONANDRETIREMENT" ]
    },
    {
      "alias": "Government Aid",
      "includeLabelGroup": [ "GOVERNMENTAID" ],
      "excludeLabelGroup": [ "CHILDBENEFIT" ]
    },
    {
      "alias": "Child Benefit",
      "includeLabelGroup": [ "CHILDBENEFIT" ]
    },
    {
      "alias": "Alimony",
      "includeLabelGroup": [ "ALIMONY" ]
    },
    {
      "alias": "Cash Deposit",
      "includeLabelGroup": [ "CASHDEPOSIT" ]
    },
    {
      "alias": "Student Funding",
      "includeLabelGroup": [ "STUDENT_FUNDING" ]
    },
    {
      "alias": "Gambling Income",
      "includeLabelGroup": [ "GAMBLINGINCOME" ]
    },
    {
      "alias": "Operating Revenue",
      "includeLabelGroup": [ "OPERATING_REVENUE" ]
    },
    {
      "alias": "Tax Refund",
      "includeLabelGroup": [ "TAX_REFUND" ]
    },
    {
      "alias": "Loan Disbursement",
      "includeLabelGroup": [ "LOAN_DISBURSEMENT" ]
    },
    {
      "alias": "Rebookings",
      "includeLabelGroup": [
        "REBOOKING_INCOME",
        "PRIVATE_WITHDRAWAL_INCOME",
        "PRIVATE_DEPOSIT_INCOME"
      ]
    }
  ]
}

Used data fields

Incoming 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.income and the type will be INCOME.

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
`transactionsStartDate`	Date of the account first transaction, regardless of the report period under review, in the format '`YYYY-MM-DD`' (CET Europe / Berlin). This field takes into consideration all the transactions of the account, irrespectively of the assigned to them label.
`accountType`	Type of the account. Can be: `CHECKING` `SAVINGS` `CREDITCARD` `SECURITY` `LOAN` `POCKET` `MEMBERSHIP` `BUILDING_SAVINGS`
`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
`transactionId`	Transaction UUID.	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
`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
`seizureInformation`	Extracted details for transactions with related to wage seizure. It contains the seizure amount extracted from the purpose, when possible.	no
`chargebackInformation`	Chargeback amount extracted from the transaction’s purpose. When it is possible to extract the chargeback amount, the extracted value is used in the calculations of the other fields and monthly objects. When extraction is not possible, the amount of the transaction is used instead.

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, the number of transactions, and the list of transaction ids behind it are always indicated.

If showOnlyCompleteMonths=false, the list of months is calculated between transactionsStartDate of the report and endDate of the report, hence both complete and incomplete months are included.

If showOnlyCompleteMonths=true, only the list of complete months between transactionsStartDate of the report and endDate of the report, is included.

All accounts are taken into consideration for the monthly objects.

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,medianTotalMonthlyAmount,totalTransactionsCount and totalTransactionsAmount.

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

Field	Description	Mandatory
`totalIncome`	Income (including salary and other income sources) organized by months.	yes
`salary`	Salary data organized by months.	yes
`rebookings`	Rebooking income of the customer between 2 own or accessible accounts or private deposits. 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
`capitalIncome`	Capital income data, organized by months.	no
`rentalIncome`	Rental income data, organized by months.	no
`pensionAndRetirement`	Pension and retirement income, organized by months.	no
`governmentAid`	Government aid income, organized by months.	no
`alimony`	Alimony aid income, organized by months.	no
`cashDeposit`	Cash deposit income, organized by months.	no
`childBenefit`	Child benefit income, organized by months.	no
`studentGrant`	Student grant income, organized by months.	no
`gamblingIncome`	Gamling income, organized by months.	no
`operatingRevenue`	Income, generated from primary business activities.	no
`taxRefund`	Tax refund income, organized by months.	no
`loanDisbursement`	Loan disbursements, organized by months.	no