Introduction to Contract Detection

Learn more about our Contract Detection, which allows you to recognize contracts and contract data from transactions.

What it solves

To find out what financial obligations the customer already has, it is important to know which contracts are existing and how much the customer pays for them. In addition, the contract detection shows the regularity of payments for these contracts and who the contract partners are. This information can be used to identify potential savings and switching options.

Contract Detection Report

With Contract Detection, it is not only possible to identify contracts but also to extract details. The Contract Detection reads out account information and outputs the existing contracts, as well as information about the contract partners.
As a result, you get a statement whether it is one of the following types:

Loan Contracts

Loan contracts recognize all loan contracts assigned to the customer. The report contains all transactions that are in the authorized time period. This provides an overview of the customer's financial situation and shows which obligations already exist. Any over-indebtedness can thus be detected and clearly displayed with a simple evaluation.

The Loan Contracts can be created with the report type CONTRACTSLOAN.

Loan Validated Contracts

With Loan Validated Contracts, it is possible to investigate whether the customer has indicated all relevant accounts (and thus all loans running on him). This is possible by comparing the loans deposited with SCHUFA. On the one hand, this comparison can be used to find out whether the customer has provided the correct information in the application. On the other hand, you get an initial insight into the customer's contract situation without a credit report.

The Loan Validated Contracts can be created with the report type CONTRACTSLOANVALIDATOR.

Insurance Contracts

Insurance contracts output all information on insurance contracts that run on the customer's account. This includes both the type of insurance and the amount paid for it. This makes it possible to record, analyze and possibly optimize the customer's current insurance status. In addition, it is possible to find out which risks the customer is insured against, which is important, for example, in the case of a credit application in order to be able to assess the credit default risk.

The Insurance Contracts can be created with the report type CONTRACTSINSURANCE.

Telecommunication Contracts

This report contains all contracts that the customer has concluded regarding telecommunications. Among other things, it contains the contractual partners and the amount paid, which makes it possible to see whether a change to a different provider might make sense. This makes it possible to find out how many contracts relating to telecommunications are already in place for the customer, and thus draw conclusions about his financial situation and lifestyle.

The Telecommunications Contracts can be created with the report type CONTRACTSTELECOMMUNICATION.

Electricity Contracts

The Electricity Contracts report shows how much the customer pays for electricity, which is especially significant in today's times of increased energy prices. Through this report, it is possible to find out what kind of electricity contract exists and with which provider. The debited amount can also be used to determine whether the customer has any potential for savings.

The Electricity Contracts can be created with the report type CONTRACTSELECTRICITY.

Gas Contracts

The Gas Contracts report shows how much the customer pays for gas, which is especially important in today's times of increased energy prices. The information obtained also makes it possible to deduce whether the customer uses relatively much or little energy, whether he may be paying too much for his contract, and which gas supplier he is with.

The Electricity Contracts can be created with the report type CONTRACTSGAS.

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 itself is divided into the following sections.

Main Section

Depending on the report type, the contract reports can be found in different sections.

Contract Report Type	Report Type Enum	Section
Loan Contracts	`CONTRACTSLOAN`	`$.reports.contractsLoan`
Loan Validated Contracts	`CONTRACTSLOANVALIDATOR`	`$.contractsLoanValidator`
Insurance Contracts	`CONTRACTSINSURANCE`	`$.reports.contractsInsurance`
Telecommunication Contracts	`CONTRACTSTELECOMMUNICATION`	`$.reports.contractsTelecommunication`
Electricity Contracts	`CONTRACTSELECTRICITY`	`$.reports.contractsElectricity`
Gas Contracts	`CONTRACTSGAS`	`$.reports.contractsGas`

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

Additional fields for contracts are:

Field	Description	Mandatory
`countContracts`	The total count of all detected contracts.
`contractsData`	List of detected contracts information.	no

Contracts Data Section

The account data section can be found under the contractsData field.
Depending on the quality of the output transactions, more or less data may appear here.

Field	Description	Mandatory
`contractId`	The unique ID, which was created for this contract. This ID is then referenced in the transactions.	yes for response
`contractType`	Describes the type of the contract. This can be `REALESTATELOAN`, `LOANANDINTEREST`, `GAS` and many more. For more details, please visit our API Documentation.	yes for response
`contractSource`	Describes the source from which the contract was detected. Can be `BANKING`, `SCHUFA` or `BANKING_AND_SCHUFA`.	yes
`matchedPeriod`	Period of the contract. The period is not provided in case the report returns fewer than two transactions for the defined contract within specified `maxDaysForCase`. Can be `WEEKLY`, `BI-WEEKLY`, `MONTHLY`, `QUARTERLY`, `HALF-YEARLY` or `YEARLY`.	no
`matchedContractStatus`	Activity status of the contract for Loan Validation Contracts and describes the status from SCHUFA. Can be `ACTIVE`, `INACTIVE` or `UNKNOWN`.	no
`newContract`	`true`, if it is the first report, where the given contract is present.	no
`contractStatus`	Activity status of the contract. Can be `ACTIVE`, `INACTIVE` or `UNKNOWN`.	no
`companyName`	The name of the company with which the contract was concluded.	no
`customerNumber`	Customer number of the contract	no
`contractNumber`	Number of the detected contract	no
`companyDetails`	Data object of the company with which the contract was concluded. Contains contact and address data, if available.	no
`billing`	Object, which contains the billing history of the contract.	no
`schufaContractDetails`	Object, which contains contract details from SCHUFA. Only available for Loan Validation Contracts.	no

Billing Information Section

In the section below billing, information on previous payments can be accessed.

Field	Description	Mandatory
`period`	Period of the contract. The period is not provided in case the report returns fewer than two transactions for the defined contract within specified `maxDaysForCase`. Can be `WEEKLY`, `BI-WEEKLY`, `MONTHLY`, `QUARTERLY`, `HALF-YEARLY` or `YEARLY`.	no
`firstBillingDate`	First billing date detected for this contract within the specified `maxDaysForCase` period in the format `YYYY-MM-DD HH:MM:SS` (CET Europe / Berlin).	no
`lastBillingDate`	Last billing date detected for this contract within the specified `maxDaysForCase` period in the format `YYYY-MM-DD HH:MM:SS` (CET Europe / Berlin).	no
`lastBillingAmount`	The amount of last billing detected for this contract.	no
`averageContractIncome`	Average amount obtained for the contract within the specified `maxDaysForCase` period.	yes
`averageContractSpending`	Average amount paid for the contract within the specified `maxDaysForCase` period.	yes
`totalContractIncome`	Total amount obtained for the contract within the specified `maxDaysForCase` period.	yes
`totalContractSpending`	Total amount paid for the contract within the specified `maxDaysForCase` period.	yes
`totalBillingsCount`	Total count of billings for the contract within the specified `maxDaysForCase` period.	yes
`history`	List of objects with the settlement history, which contains the settled amounts, date and transactionId.	no

SCHUFA Contract Details

This section can be found under schufaContractDetails. The data returned via SCHUFA for a contract is displayed here.

Field	Description	Mandatory
`schufaType`	SCHUFA characteristic (Merkmale).	no
`description`	To SCHUFA reported description of the contract.	no
`date`	Contract date in the format `YYYY-MM-DD`. Depending on the feature code, the date can represent various facts relating to the contract's subject matter, e.g. the date of the contract or the date of the first installment (e.g. in the case of loans). In the case of credit rates, the current date is often specified here. Sometimes the field may return the data, like `UNBEFRISTET` for unfixed contracts, thus making the information in this field not reliable.	no
`amount`	Amount, paid for the contract.	no
`currency`	Currency of the amount according to ISO standard as 3-digit alphabetical code.	no
`numberOfRates`	Number of installments, that have been agreed in terms of the contract.	no
`typeOfRate`	Period of the contract reported to SCHUFA. The period is not provided in case the report returns fewer than two transactions for the defined contract within specified `maxDaysForCase`. Can be `WEEKLY`, `BI-WEEKLY`, `MONTHLY`, `QUARTERLY`, `HALF-YEARLY` or `YEARLY`.	no
`accountNumber`	The account number, which is used for the contract.	no
`contractStatus`	Status of the contract reported by SCHUFA. Can be `ACTIVE`, `INACTIVE` or `UNKNOWN`.

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
`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
`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

In addition to the regular transaction data, a transaction in Contract Reports includes a list of contractIds. These contain the ID(s) of the contracts to which they have been assigned.
Since there can be multiple contracts in a transaction (e.g. insurance), this value is a list.