Private Financials
Overview
This document provides diagrams that illustrate relationships within the Private Financials domain. By understanding this model, you can visualize the complete data structure behind the Private Financials API, including how classes and attributes are organized and how their relationships are represented.
For a detailed description of each class and its attributes, refer to Private Financials API.
Private financials
Lenders can determine whether a person can afford to borrow and repay the loan based on their private financial information. Private financial information includes personal financial data collected for underwriting and risk assessment.
The private financial domain contains the following subdomains:
Incomes
- To view the diagram in full size, right-click and select Open Image in New Tab.
- To learn how to read the diagram, see How to read these diagrams.
The income class collects all of a borrower’s income sources in one place, such as salary, business revenue, or rental income. Lenders use this information to assess repayment capacity. Lenders can add general remarks to the overall income record to provide additional context or details.
You can register multiple income sources for each counterparty and add remarks for context. Each income record is linked to a counterparty, a specific process, a tenant, and a white label brand.
To retrieve income sources and statements, use the Private Income Query API.
Income source
Lenders need to assess a borrower’s income source to determine their ability to meet mortgage repayments. An income source is any type of income that matters for a loan application. Each source stores specific details. For example, shareholder income includes dividend information, while employment income includes salary details and employer information.
Every income source has a gross annual income, but how this is calculated depends on the category. If no special rule applies, it’s stored as a single value.
Most income sources also have a type that explains how the income is earned. This type can be country-specific or general.
Currently, the following income sources are supported:
- Employment income
- Social benefit income
- Entrepreneur income
- Shareholder income
- Pension income
- Rental income
- Other income
Employment income
Employment income refers to the money a person earns for work performed as an employee.
The EmploymentDetails class stores job and employer details, such as company name, location, and sector code. Sector information uses the same format as defined in Counterparties. It also includes whether the employee is on probation, the date of the payslip used as proof of income, and an employer statement confirming the validity of the employment contract.
Employment income includes two categories: fixed and temporary.
Fixed employment income
Fixed employment income refers to income from permanent jobs.
If an employee expects a raise starting from a specific date, FutureIncome can be used to record the start date and the new amount of annual gross income, which is the amount the employee expects to earn after the raise begins.
A FixedEmploymentIncome includes one or more EmploymentIncomeComponent, each with a type (IncomeComponentType) and an amount. Each IncomeComponentType is country-specific and defines whether the income is fixed or variable, active for new sources, and has translated names for supported languages. The total annual gross income is the sum of all EmploymentIncomeComponent amounts. You can refer to the following examples.
Below is an example of EmploymentIncomeComponent:
| Type | Amount |
|---|---|
| gross-annual-salary | 35000 |
| holiday-allowance | 2800 |
| fixed-13th-month | 3000 |
| overtime | 2500 |
| commission | 3000 |
Below is an example of IncomeComponentType:
| Code | CountryCode | IsVariable | Names | IsActive | IsRequired |
|---|---|---|---|---|---|
| gross-annual-salary | US | False | nl: Bruto jaarsalaris, en: Gross annual salary | True | True |
| holiday-allowance | US | False | nl: Vakantietoeslag, en: Holiday bonus | True | False |
| fixed-13th-month | US | False | nl: Vaste 13e maand, en: Fixed 13th month | True | False |
| overtime | US | True | nl: Overwerk, en: Overtime | True | False |
| commission | US | True | nl: Provisie, en: Commission | True | False |
Temporary employment income
Temporary employment income refers to income from short-term jobs. In addition to the current gross annual salary, it includes income from the past three years. The annual income is the average of the past three years, but it cannot exceed the income of the most recent year.
Social benefits income
Social benefits income refers to money received from social benefit programs. Each social benefits income type is a country-specific type. For example, AOW, WAZ, or WW are social benefit types in the Netherlands.
Entrepreneur income
Entrepreneur income is the income an entrepreneur earns from their business. To calculate a representative amount, the system records the gross annual income for the past three years. This calculated amount can be overridden if needed. The record includes the company’s registration number, name, address, and legal form. The legal form information is stored following the same formats in Counterparties.
Shareholder income
Shareholder income is the income received from being a major shareholder in a company. This usually comes from dividends, either from profits or reserves. The duration of dividend payments is based on the start and end dates of the IncomeSource. Each type is linked to a predefined IncomeSourceType.
Pension income
Pension income is money received from retirement savings. Currently, there are two supported types for all countries:
- Workplace pension: A pension paid to the employee after reaching the retirement age. This pension is a contribution paid by both the employee and employer during the employee’s working time.
- Dependants’ pension: A pension paid regularly to the surviving spouse or civil partner after the employee has passed away.
Rental income
Rental income is money earned from renting out real estate. The related costs, which are AnnualOperationalCosts, AnnualLoanInterestAmount, and AnnualLoanRepayment, can be entered manually or calculated using norm rates. If norm rates are used, set UsesNormRates to true and leave these fields empty. Calculations are handled by the Akkuro Lending.
It is not required to have a loan for a rental income.
The calculation of gross annual income for rental income :
GrossAnnualIncome = AnnualRentalIncomeBeforeCosts - AnnualOperationalCosts - AnnualLoanInterestAmount - AnnualLoanRepayment
Other income
Other income covers all income types not included in the main categories. Currently, there are four specific income types under this category:
- Disability insurance
- Income from disposable assets (savings)
- Income from disposable assets (securities)
- Partner alimony
If your income type still does not fall under any of the aforementioned types, specify the type as Other income with an optional description.
Obligations
- To view the diagram in full size, right-click and select Open Image in New Tab.
- To learn how to read the diagram, see How to read these diagrams.
Obligation refers to financial commitments or liabilities that a person must pay regularly, such as loans, credit card balances, mortgages, and other recurring expenses. These reduce the amount of money available and affect a borrower’s ability to take on additional debt.
You can register multiple obligation sources for each counterparty and add remarks for context. Each obligation record is linked to a counterparty, a specific process, a tenant, and a white label brand.
Obligation sources are grouped into several categories:
To retrieve obligation sources and statements, use the Private Obligation Statement Query API.
Partner alimony
Partner alimony is the annual payment a borrower must make to their ex-partner as stated in the signed divorce agreement. Unlike other obligation categories, this uses an annual amount.
Student loan
A student loan is money borrowed to pay for higher education while the borrower was a student.
For example, in the Netherlands, “student loan” usually refers to a loan from the Dutch institution (DUO). When calculating the borrower’s maximum mortgage amount, the DUO student loan must be included. The amount considered depends on the start date of the student loan and is defined by Dutch law.
Rental obligation
Rental obligation refers to the borrower’s responsibility to pay rent for their personal residence. For example, if a borrower pays €1,200 per month in rent, this amount counts as a rental obligation when assessing financial commitments.
Credit
Credit refers to any non-mortgage loan with a financial institution, such as a bank or a leasing company. These loans are grouped into several specific types, which can vary by country and require extra details.
Currently, the system supports these credit types:
- Closed-end credit: Credit with fixed start and end dates. This is typically used for general consumptive use.
- Overdraft: Debt from a negative bank account balance. This has a start date but no end date.
- Credit card: Outstanding debt on a credit card. This has a start date but no end date.
- Open-end credit: Credit with a start date but no end date. You only know the credit limit or the initial lump sum available. Usually linked to the borrower’s bank account and can be used for any purpose, often covering short-term overdrafts.
- Telecom credit: Debt for paying off their phone as part of a monthly contract. The principal amount is the value of the phone. An end date is required.
- Operational car lease: A car lease contract where the borrower makes monthly payments to use the car for a defined term with a fixed start and end date.
Mortgage
A mortgage refers to any mortgage loan the borrower has, including loans for their own residence. Each mortgage is classified by country-specific types and may include a credit bureau registration code.
For example, in the Netherlands, the mortgage should indicate if it falls under Fiscal Box 1 (the tax classification for income from work and home ownership). If so, provide the fiscalEndDate. Otherwise, leave this field empty.
Currently, two types are supported in the Netherlands:
- Mortgage for a private property: A mortgage for the borrower’s private and primary home.
- Mortgage for a rental property: A mortgage for a property that is not the borrower’s primary home, such as a holiday house or a student flat for rental purposes.
Loan
This covers loans that are not mortgages or standard credit products, such as money borrowed from family or an employer. Each loan type is country-specific, and you can provide an actual monthly obligation amount for more accurate calculations.
In the Netherlands, the following types are supported:
- Loan from employer: A loan borrowed from their employer, usually repaid via their salary.
- Family loan: A loan borrowed from their family members with regular repayments.
- Company loan: A loan borrowed from their own company for personal expenses, which creates a regular repayment obligation. For example, a company director uses the company’s account to pay for personal expenses, such as a holiday.
- Debt recognition to children: This is a Dutch concept (Schenking op papier) where parents donate money to their children on paper while retaining the funds. Tax authorities treat this as a loan, and parents must pay interest to their children.
Other obligation
Use this category for any payment obligation that does not fall under the categories listed above.
Maximum mortgage
- To view the diagram in full size, right-click and select Open Image in New Tab.
- To learn how to read the diagram, see How to read these diagrams.
Maximum mortgage represents the result of a maximum mortgage calculation, including the input data and a set of assessments for each taxable income category.
A taxable income category defines how a specific type of income is taxed, which impacts the mortgage calculation. For example, in the Netherlands, income is classified into Box 1, 2 and 3. Calculations are usually done for Box 1 and 3.
To retrieve maximum mortgage calculations and results, use the Maximum Mortgages Query API.
Input
The input data represents all information used to calculate the maximum mortgage. In addition to the method, initiator, and calculation date, the input data consists of the following three main parts:
Counterparty input
For each counterparty used in the calculation, the following information is stored:
- Marital status
- Date of birth
- Income
- Obligations
Collateral object input
If a collateral object is a land object, the annual ground rent of the leasehold is stored, if applicable.
If a collateral object is a real estate object, energy performance information is stored, including the energy label, cost of energy-saving facilities, and the available savings budget.
Loan part input
For each loan part, the calculation stores general information, such as:
- Start date and end date
- Loan limit
- Repayment type
- Interest rate
- End date of the fixed-rate period
- End date of the tax-deductible period
Assessment
Each calculation produces an assessment for each taxable income category. Each assessment includes the maximum allowed annuity mortgage, the maximum allowed mortgage based on actual payments, and multiple assessment moments.
AssessmentMoment
An AssessmentMoment contains the assessment details for a specific moment in time. Each moment starts after the previous one ends and concludes for one or more reasons defined by AssessmentMomentType. The end date of the moment is specified by CalculationMoment.
ExtraRoomInAffordableMortgage
In some situations, the law allows borrowing extra money beyond the normal limit. This extra allowance is recorded in the ExtraRoomInAffordableMortgage class, which includes the total and monthly extra amounts allowed, as well as a list of extra rooms. Each extra room contains the specific reason for granting this additional borrowing capacity.
Currently, the supported reasons are:
| Reason | Description |
|---|---|
EnergyLabel | Extra borrowing capacity granted based on the energy label of the mortgaged collateral object. |
EnergySavingMeasures | Extra borrowing capacity granted for improvements that reduce the collateral object’s energy consumption. |
SinglePersonHousehold | Extra borrowing capacity granted for borrowers who live alone. |