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.

With the Contracts Report, it is possible to identify contracts and extract contract details for more contract types. The Contracts Report provides a comprehensive overview of the customer’s contracts, while providing information about the counterparts involved, the amounts paid within the contracts, and the frequency of these payments.

Used data fields

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

API endpoints

A full API schema can be found here:

Create a contract report: https://docs.finapi.io/?product=di#post-/cases/-caseId-/report/contract
Get a contract report: https://docs.finapi.io/?product=di#post-/cases/-caseId-/reports/contract/-reportId-

To ensure high data quality, the data undergoes an advanced analysis of contract transactions. This process considers the complete transaction history to group and identify contracts that may occur on an annual basis. As a result, the report might take some additional time to become available after generation.

Use polling to get the state of the requested report. While the analysis is still in progress, a 423 RESOURCE_LOCKED code will be returned with the message Analysis of the transaction is still in progress or not started.
Use a callback URL. By using the callback URL within the report creation endpoint you will be informed in case of the report is available.

Main Section

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

Field	Description	Mandatory
`id`	UUID of the report	yes
`dateCreation`	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
`dateStart`	Timestamp of the start date of the reporting period under review in the format `YYYY-MM-DD` (CET Europe / Berlin).	yes
`dateEnd`	Timestamp of the end date of the reporting period under review in the format `YYYY-MM-DD` (CET Europe / Berlin).	yes
`daysOfReport`	The number of full days, that the reporting period under review contains.	yes
`contractData`	List of detected contracts.	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.

Field	Description	Mandatory
`bankName`	Name of the bank.	no
`bankId`	Unique identifier of the Bank, generated by finAPI.	no
`accountIban`	IBAN of the bank account.	no
`accountId`	Unique identifier of the bank account belonging to the imported bank connection.	no
`accountHolderName`	Account holder name.	no
`accountHolderType`	Type of the account holder. Can be: `PRIVATE` - the account belongs to one person. `JOINT` - the account belongs to more than one person. `COMPANY` - the account belongs to a legal entity (company). `SELF_EMPLOYER` - the account where the account holder name is a private person, but where, for example, salary is paid out or trade tax transfers are transferred to the tax office. `UNKNOWN` - the account holder type cannot be defined.	no
`accountCurrency`	Currency as 3-character code.	no
`accountType`	Type of the account. Can be: `CHECKING` `SAVINGS` `CREDITCARD` `SECURITY` `LOAN` `POCKET` `MEMBERSHIP` `BUILDING_SAVINGS`	no
`transactionsStartDate`	Date of the account first transaction, regardless of the period under review, in the format `YYYY-MM-DD` (CET Europe / Berlin). This field takes into consideration all the transactions of the account, respectively of the assigned to them label.	no

Contract Information Section

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

Field	Description	Mandatory
`id`	The unique ID, which was created for this contract.	yes for response
`source`	Describes the source from which the contract was detected. Can be `BANKING`, `SCHUFA` or `BANKING_AND_SCHUFA`. At the moment, the endpoint supports only `BANKING`, therefore contracts detected by finAPI algorithm.	no
`status`	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
`contractDetails.customerNumber`	Extracted customer number of the contract. Please note that `contractDetails` is an array of `[customerNumber, contractNumber, amount]`	no
`contractDetails.contractNumber`	Extracted number of the detected contract. Please note that `contractDetails` is an array of `[customerNumber, contractNumber, amount]`	no
`contractDetails.amount`	Extracted amount of the detected contract. Please note that `contractDetails` is an array of `[customerNumber, contractNumber, amount]`	no
`labels`	List of the labels of the transactions included in the 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

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
`dateFirst`	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
`dateLast`	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
`lastAmount`	The amount of last billing detected for this contract.	no
`averageIncome`	Average amount obtained for the contract within the specified `maxDaysForCase` period.	no
`averageSpending`	Average amount paid for the contract within the specified `maxDaysForCase` period.	no
`totalIncome`	Total amount obtained for the contract within the specified `maxDaysForCase` period.	no
`totalSpending`	Total amount paid for the contract within the specified `maxDaysForCase` period.	no
`totalBillings`	Total count of billings for the contract within the specified `maxDaysForCase` period.	no
`history`	List of objects with the settlement history, which contains the settled amounts, date, transactionId and purpose.	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.