Welcome to Data Intelligence!
With finAPI Data Intelligence REST services we want to provide a deeper insight into the picture that describes a consumer’s financial situation based on our Open Banking solution.
...
Furthermore, we use cutting-edge technology for constantly enhancing our services, from data analysis pipelines to an event-driven system, which is built 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 that 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 be created in DI:
Bank Connection data sources (imported via Web Form 2.0)
Schufa Credit Check data sources (provided by Schufa WS)
Transaction data sources (where accounts and transactions for analysis are provided via API endpoint)
Bank Connection Data Source
Initial Import
...
Bank Connection Data Source
To create a data source (bank connection) in DI:
...
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 are:
...
NOTE: Synchronization endpoint should not be used for data source update.
Schufa Credit Check Data Source
The major prerequisites for creating a Schufa Credit Check data source are being authorized in DI and having a set test account on the Schufa side.
...
NOTE: In comparison to Bank Connection Data Source, the process of creation of the 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.
Transaction Data Source
A transaction data source allows the usage of Data Intelligence, if you have your own source to provide account and transaction data, and you want to label and analyse it.
...
For all further details on the request and response body objects refer to the API description: https://docs.finapi.io/?product=di.
2. Case Creation
The major prerequisite for creating a case is getting the IDs of the data sources (dataSourceId) from Step 1, based on which the reports in the given case will be created.
...
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 get a report of a particular type (Chargebacks, Gambling, B2B Balances, Insurance) and of a particular category (Risk, Cash Flow, B2B, Contracts), make a call to GET <DI_URL>/api/v1/reports/{reportId}.
Continuous Reports
It is possible to create a report, that continues an existing/previous report, by making a call to POST <DI_URL>/api/v1/cases/{caseId}/report, which includes the object continuousReport.
...
NOTE: Every case file may have a maximum of 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 Reports
Calling the endpoint GET <DI_URL>/api/v1/labels?reportType=<REPORT_TYPE> returns the currently defined labels, with their descriptions.
...
For all further details on the request and response body objects refer to the API description: https://docs.finapi.io/?product=di.
Digital Account Check (DAC) Reports
DAC services allow the creation of a case file with multiple Risk and/or Cash Flow reports within a single API call: POST<DI_URL>/api/v1/dacCases/loan
...
The case file id returned in the response of the call should be used as an input path parameter for GET<DI_URL>/api/v1/cases/{caseId}/reports to retrieve the DAC report results.
DAC Report | Included Risk / Cash Flow Reports |
|---|---|
DAC for Loan |
|
4. Using Triggers
DI allows its clients to set triggers for a continuous report (see above). Triggers are special conditions, set by the client. Once any of the created child reports meet the defined condition, the user gets notified, that the trigger even took place.
...
Select one of the pre-defined triggers via POST <DI_URL>/api/v1/reports/{reportId}/triggers/cashFlow
Create your own trigger via POST <DI_URL>/api/v1/reports/{reportId}/triggers
Pre-defined triggers
For example, if the client wants to get notified when the user’s salary amount will change, he can use SALARYAMOUNTCHANGE pre-defined trigger. For this make a call to POST <DI_URL>/api/v1/reports/{reportId}/triggers/cashFlow with the triggerType = SALARYAMOUNTCHANGE and reportId of the initial (parent) report.
Creating your own trigger
In case none of the pre-defined triggers can cover the client's needs, the client can create his own customized trigger.
Example 1
For example, if the client wants to get notified once the user concluded a new health insurance contract, the following trigger for continuous Contracts Report for Insurances can be set via POST <DI_URL>/api/v1/reports/{reportId}/triggers. To do this the client should find the contracts of contractType= HEALTHINSURANCE AND newContract=true, to ensure that the contract is new for the user.
| Code Block |
|---|
...
"triggers": [
{
"path": "$.contractsData[*].contractType",
"operator": "EQ",
"value": "HEALTHINSURANCE",
”and": [
{
"path": "$.contractsData[*].newContract",
"operator": "EQ",
"value": true
}
]
} |
Example 2
Another example of own triggers creation can be as follows: the client needs to be notified once a user has new gambling or debt collection-related transactions, to define risk level for the user’s account. To do this, the client should find the transactions with GAMBLING OR DEBTCOLLECTION labels.
| Code Block |
|---|
...
"triggers": [
{
"path": "$.accountData[*].transactions[*].labels,
"operator": "EQ",
"value": "GAMBLING"
},
{
"path": "$.accountData[*].transactions[*].labels",
"operator": "EQ",
"value": "DEBTCOLLECTION"
}
]
}
|
Trigger Results
The results of the trigger evaluation will be included in a continuous report, which means a report that has been created with a provided continuousReport object during its creation.
5. User’s DI Data Deletion,
In case it is needed to remove the DI data of the user, such as the created Data Sources, Reports, and Cases, theDELETE <DI_URL>/api/v1/ user endpoint can be used.
To delete the user’s data it is mandatory to pass a valid user access_token.
...
To ensure whether the deletion process has been finalized for the user, the obtained deletionId should be used for GET <DI_URL>/api/v1/user/status/delete/{deletionId} call. The response of the call is aimed at providing detailed data on the status of data deletion at each DI module (application).
...