Data Intelligence

Welcome to Data Intelligence!

With finAPI Data Intelligence REST services we want to provide a deeper insight into the picture that describes the financial situation of a consumer based on our Open Banking solution.

We already provide intelligent banking API services suitable for an individualized personal finance management experience of an end user with our Access PFM product. However, with Data Intelligence we can provide our customers with an even clearer picture of the financial situation of their consumers and users.

To achieve this we structured our Data Intelligence services accordingly:

• Risk Reports section provides reports related to the user's banking transactions which might indicate a payment risk if for e.g. our customer provides goods with a payment plan to this consumer. We detect these risky transactions and bundle them under one report, which an application on our customer's side can consume within seconds.

• To gain a deeper understanding of the cash flows of your end users, we offer the Cash Flow Reports section. Here is a variety of income and expenditure-related reports, in which we aggregate and summarize the according transactions belonging to a specific field, like insurance, income or rent and living, etc.

To provide data in the highest possible quality, Data Intelligence Open Finance services analyse the external data received from finAPI Access (finAPI API Documentation ) via finAPI Web Form 2.0 (WebForm 2.0 Documentation), such as account data, transactions, bank data, by using a combination of an expert knowledge system, driven by clearly defined rules, and machine learning approach for providing a label coverage for approximately 80% of all transactions and aggregation the information into the decision-ready state.

Furthermore, we use cutting-edge technology for constantly enhancing our services, from data analysis pipelines to an event-driven system, which is build in scalable modules, that you also may use in a proprietary environment or as a SaaS. If you are interested in this kind of usage or want to know more, please feel free to contact us for an offer. We are looking forward to hearing from you!

Follow-up

The following sections describe the technical steps needed for integration. It is an additional resource which completes our Swagger description of the REST API. If you experience any problems with our integration or just have some questions, please contact our support at any time at support@finapi.io. Our customer success team is happy to help you to bring your services consuming finAPI REST APIs to success.

1. Data Source Import

The following types of data sources can now be created in DI:

• Bank Connection data sources (imported via Web Form 2.0)

• Schufa Credit Check data sources (provided by Schufa WS)

Bank Connection Data Source

Initial Import

To create a data source (bank connection) in DI:

1. Authorize/create a user (-identity), as described in Getting Started - Authorization as a Process or UserPreview. The sequence diagram above show authorization as a user. Alternatively it is possible to create a process and obtain a OAuth token for the process.

2. Import the Bank Connection with the help of finAPI Web Form 2.0 (POST / webForms/bankConnectionImport).

3. Upon successful completion of the SCA (web form), make a call to the DI POST / dataSources / bankConnections / synchronization with included callbackUrl (optional) and retrieve the imported bank connection with the DI dataSourceId.

3a. In case the callbackUrl has been provided, DI will send a notification to the client once the Data Source synchronization is finalized (with SUCCESSFUL or ERROR)

3b. In case the callbackUrl has not been provided, poll GET / dataSources / {dataSourceId} / status until the data source status is SUCCESSFUL or ERROR.

NOTE: The bank connection is not considered as imported until the SCA (webform) is completed successfully.

NOTE: The bank connection that was imported through Web Form 2.0 will be reflected in DI only once the POST / dataSources / bankConnections/synchronization call is made. Before the call is made, the DI data base has no data sources (bank connections) stored for a particular user.

NOTE: Recommended polling frequency of the Data source status is 1 sec. Maximum recommended polling time - 5 min.

Update Initiation

The major prerequisites for updating a data source (bank connection) in DI is:

1. Data source synchronization call returned bank connection in status FAILED

2. Calling GET/dataSources/{dataSourceId}/status resulted in status FAILED and code UPDATE_REQUIRED.

To update a data source (bank connection) in DI:

1. Update the imported earlier Bank Connection with the help of finAPI Web Form 2.0 (POST /api/tasks/backgroundUpdate ).

2. Upon successful completion of the SCA (web form), poll the DI POST / dataSources / {dataSourceId} / status until the data source status is SUCCESSFUL.

NOTE: Recommended polling frequency of the Data source status is 1 sec. Maximum recommended polling time - 5 min.

NOTE: Synchronization endpoint should not be used for the purposes of the data source update.

Schufa Credit Check Data Source

The major prerequisites for creating a Schufa Credit Check data source is being authorized in DI and having a set test account on Schufa side.

To create a Schufa Credit Check data source through DI, make a call to DI POST/dataSources/schufaCreditCheck and pass the following request body, where only the schufaId, title, placeOfBirth and country are optional for completion.

The Schufa Credit Check data resource creation response body looks as follows (in case performed successfully):

NOTE: In comparison to Bank Connection Data Source, the process of creation of Schufa Credit Check Data source is synchronous. Thus in case the dataSourceId is obtained, the data source is considered to be successfully imported and requires no further actions from the client’s side.

2. Case Creation

The major prerequisite for creating a case is getting the IDs of the data sources (dataSourceId) from Step 1, on the basis of which the reports in the given case will be created.

To create a case, make a call to POST / cases and pass the following parameters:

• dataSourceids= the IDs of all the data sources (dataSourceId) or particular accounts inside these data sources (in case of Bank Connections) (accountId) on the basis of which the reports in the being created case will be provided.

• maxDaysForCase = number of days, the data from which will be analysed for reports creation (applicable for Bank Connection Data Sources only).

  Example: A case file is created on Oct 10, 2020 and has a Bank Connection Data Source inside; maxDaysForCase=9 => all the reports that will be created in this case file, will have the analysed data from the period Oct 1, 2020 to Oct 10, 2020 .

The case creation response body looks as follows (in case performed successfully):

NOTE: The case file creation won’t be successful until the data sources connected with it have the data import finished (in case of Bank Connection Data Sources).

NOTE: The maxDaysForCase parameter limits the range of data provided in Bank Connection Data Sources, but does not influence in any way the data inside the Schufa Credit Check Data Source.

3. Reports Creation & Getting

Risk, Cash Flow, B2B, Contracts Reports

The major prerequisite for creating and getting the report is having the caseId of the successfully created case file from Step 2.

To create a report of a particular type (Chargebacks, Gambling, B2B Balances, Insurance) and of particular category (Risk, Cash Flow, B2B, Contracts ) , make a call to POST/cases/{caseId}/reports/ <report_category>/<report_type>.

NOTE: If there is a need for report to be re-generated automatically in particular time periods without additional user interaction, the interval and intervalPeriod fields need to be specified. Such a report will be considered continuous and will have associated with it child reports, created automatically inside of the same case file.

NOTE: In case the report is considered continuous, the time span of transactions, that will be analysed for child reports is defined by interval and intervalPeriod , not by maxDaysForCase parameter.

To get a report of a particular type (Chargebacks, Gambling, B2B Balances, Insurance) and of particular category (Risk, Cash Flow, B2B, Contracts) , make a call to GET/cases/{caseId}/reports/ <report_category>/<report_type>.

NOTE: Every case file may have maximum one report of a particular type: e.g. 1 case file may have 1 Chargebacks report, 1 Gambling report and 1 Insurance Report (child reports are not taken into account for this count).

Transactions Labeling in Cash Flow and Risk Reports

DAC Reports

DAC services allow to create a case file with multiple Risk and/ or Cash Flow reports within a single API call.

The major prerequisite for creating and getting the DAC reports is getting the IDs of the data sources (dataSourceId) from Step 1, on the basis of which the reports in the given case will be created. For creation of a case with DAC report, the same rules as for Case Creation apply (see step 2).

The case file id returned in the response of the call should be used as an input path parameter for GET cases/{caseId}/reports to retrieve the DAC report results.

4. Using Triggers

DI allows its clients to set triggers for the continuous reports. Triggers are special conditions, set by the client. Once any of the created child reports meets the defined condition, the user gets notified, that the trigger even took place.

There are two ways to set triggers:

1. Select one of the pre-defined triggers via POST /reports/{reportId}/triggers/cashFlow