DI Basics

1 1. Data Source Import
- 1.1 Bank Connection Data Source
  - 1.1.1 Initial Import
  - 1.1.2 Update Initiation
- 1.2 Schufa Credit Check Data Source
2 2. Case Creation
3 3. Reports Creation & Getting
- 3.1 Risk, Cash Flow, B2B, Contracts Reports
  - 3.1.1 Transactions Labeling in Cash Flow and Risk Reports
- 3.2 DAC Reports
4 4. Using Triggers
- 4.1 Pre-defined triggers
- 4.2 Creating your own trigger
  - 4.2.1 Example 1
  - 4.2.2 Example 2
5 5. User’s DI Data Deletion

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

The major prerequisites for creating a data source in DI is:

Obtaining a user access token from Access

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

Import the Bank Connection with the help of finAPI Web Form 2.0 (POST / webForms/bankConnectionImport).
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 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:

Data source synchronization call returned bank connection in status FAILED
Calling GET/dataSources/{dataSourceId}/status resulted in status FAILED and code UPDATE_REQUIRED.

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

Update the imported earlier Bank Connection with the help of finAPI Web Form 2.0 (POST /api/tasks/backgroundUpdate ).
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.

{
  "credentials": {
    "schufaUserId": "300/01182",
    "schufaPassword": "MIEAPI12"
  },
  "consumer": {
    "schufaId": 123,
    "title": "Dr.",
    "gender": "M",
    "firstName": "Fritz",
    "lastName": "Lang",
    "dateOfBirth": "2000-01-01",
    "placeOfBirth": "Berlin",
    "currentAddress": {
      "street": "Musterstraße 7",
      "zipCode": 12345,
      "city": "Beispielstadt",
      "country": "DEU"
    }
  }
}

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

1
2
3

{
  "dataSourceId": "48f4b008-5582-413b-ab49-14f9a2317596"
}

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):

{
  "id": "5e760145-2e65-4242-ac33-488943528c93",
  "maxDaysForCase": 9,
  "creationDate": "2020-10-10 00:00:00.000",
  "dataSources": [
    {
      "id": "4e760145-2e65-4242-ac33-488943528c93",
      "creationDate": "2020-10-09 00:00:00.000"
    }
  ]
}

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.

Continuous Report Creation Example

In case the user wants Income Report to be re-generated on Monday once per two weeks AND every 5th day of the month, the request body should look as follows:
"continuousReport": {
"weeks": {
"days": [ "MONDAY" ],
"interval": 2
},
"months": {
"days": [ 5 ],
"interval": 1
}
}

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

Report Type	DI Label

Report Type	DI Label
Chargebacks	CHARGEBACKS
Gambling	GAMBLING
Debt Collection	DEBTCOLLECTION
Seizure	SEIZURE
Income	SALARY
	CAPITALINCOME
	RENTALINCOME
	PENSIONANDRETIREMENT
	GOVERNMENTAID
	ALIMONY
	CASHDEPOSIT
	INCOME
	GAMBLINGINCOME
	CHILDBENEFIT
Rent & Living Spending	UTILITIES
	REALESTATELOAN
	DOMESTICSERVICES
	RENT
	ELECTRICITY
	GAS
	TELECOMMUNICATION
	RENTANDLIVING
Insurance Spending Contracts for Insurance	DISABILITYINSURANCE
	LIABILITYINSURANCE
	LIFEINSURANCE
	CAREINSURANCE
	LEGALINSURANCE
	ACCIDENTINSURANCE
	TRAVELINSURANCE
	HEALTHINSURANCE
	SUPPLEMENTARYHEALTHINSURANCE
	HOMECONTENTINSURANCE
	HOMEINSURANCE
	PRIVATEPENSIONINSURANCE
	CARINSURANCE
	ENDOWMENTINSURANCE
	PETHEALTHINSURANCE
	PETLIABILITYINSURANCE
	PETINSURANCE
	SUPPLEMENTARYDENTALINSURANCE
	INSURANCE
Bank & Credit Spending	BANKCHARGES
	ACCOUNTTRANSFER
	LOANANDINTEREST
	CREDITCARD
	CASHWITHDRAWAL
	CARLOAN
	REALESTATELOAN
	BANKANDCREDIT
Savings Spending	SAVINGS
	BUILDINGSAVINGS
	INVESTMENTINSECURITIES
	TIMEDEPOSIT-CALLMONEY-SAVINGSACCOUNT
	ARTICLESOFVALUEANDOTHERS
Tax Spending	PAYMENTSTOPROFESSIONALASSOCIATIONS
	PROFESSIONALEDUCATION
	CRAFTSMEN
	DONATION
	ACCIDENTINSURANCE
	TAX
Travel Spending	TRAVEL
	ACCOMMODATION
	PACKAGETRIP
	TRANSPORT
Shopping Spending	SHOPPING
	FOOD
	FASHION
	OFFICESUPPLIES
	HOBBYANDGARDEN
	HOMEANDLIVING
	ONLINESHOPPING
	DEVICES
	SOFTWARE
	GOURMET
	DISCOUNTER
	GROCERIES
	BIOGROCERIES
	RESTAURANT
	ONLINEFASHION
	APPAREL
	SHOES
Mobility Spending	MOBILITY
	PETROLSTATION
	CARLOAN
	CARLEASING
	CARPURCHASE
	CARTAX
	CARFINES
	CARMAINTENANCE
	CARINSURANCE
	CAROTHERS
	MOBILITYSHARING
	PARKING
	PUBLICTRANSPORT
	RAIL
	AIRTRAVEL
	BUSTRAVEL
	CARSHARING
	CARRENTAL
	TAXI
Entertainment Spending	ENTERTAINMENT
	DIGITALMEDIA
	TV/GEZ
	TVSTREAMING
	MUSICSTREAMING
	DIGITALBOOKS
	GAMING
	BOOKS
	NEWSPAPERS
	MAGAZINES
	STATIONARY
	PRINTMEDIA
	ARTS
	FILMANDTHEATER
	MUSICEVENTS
	ARTEXPO
	SPORTS
	ACTIVESPORTS
	SPORTEVENTS
Contracts for Loan	CARLOAN
	REALESTATELOAN
	LOANANDINTEREST
	SUBSIDIZEDLOAN
	BANKANDCREDIT
Contracts for Electricity	RENTANDLIVING
Contracts for Electricity	ELECTRICITY
Contracts for Gas	`RENTANDLIVING
Contracts for Gas	GAS
Contracts for Telecommunication	RENTANDLIVING
Contracts for Telecommunication	TELECOMMUNICATION

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.

DAC Report	Included Risk / Cash Flow Reports

DAC Report	Included Risk / Cash Flow Reports
DAC for Loan	Chargebacks Debt Collection Gambling Seizure Income Rent and Living Spending

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:

Select one of the pre-defined triggers via POST /reports/{reportId}/triggers/cashFlow
Create your own trigger via POST /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 /reports/{reportId}/triggers/cashFlow with the triggerType = SALARYAMOUNTCHANGE and reportId of the created by the client continuous Income Report, that contains salary transactions.

Thus, once an automatically created Income child report contains salary transaction with the amount different to the previously created Income report, the notification with the child report details will be sent to the specified in the request body callbackUrl.

Creating your own trigger

In case none of the pre-defined triggers can cover 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 /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.

...
"triggers": [
     {
       "path": "$.contractsData[*].contractType",
       "operator": "EQ",
       "value": "HEALTHINSURANCE",
       ”and": [
          {
            "path": "$.contractsData[*].newContract",
            "operator": "EQ",
            "value": true
     }
  ]
}

Thus, once an automatically created Contracts Report for Insurance child report contains new health insurance contract, the notification with the child report details will be sent to the specified in the request body callbackUrl.

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 user’s account. To do this, the client should find the transactions with GAMBLING OR DEBTCOLLECTION labels.

...
"triggers": [
     {
       "path": "$.accountData[*].transactions[*].labels,
       "operator": "EQ",
       "value": "GAMBLING"
     },
     {
       "path": "$.accountData[*].transactions[*].labels",
       "operator": "EQ",
       "value": "DEBTCOLLECTION"
     }
  ]
}

Thus, once an automatically created Spending child report contains new gambling or debt collection transactions, the notification with the child report details will be sent to the specified in the request body callbackUrl.

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, Cases, the DELETE/ user endpoint can be used.

To delete the user’s data it is mandatory to pass a valid user access_token.

The user deletion request response will contain the deletionId:

1
2
3

{
  "deletionId": "4e760145-2e65-4242-ac33-488943528c93"
}

To ensure whether the deletion process has been finalized for the user, the obtained deletionId should be used for GET /user/status/delete/{deletionId} call. The response of the call is aimed at providing the detailed data on the status of data deletion at each DI module (application).

NOTE: The data for the user will be deleted in DI only. The data imported for the user in Access will remain unless it is deleted directly on Access side. You may re-synchronize the backends if you want to create new data sources, cases and reports.