Insights-Refresh

This starts the consumer bank data acquisition for the case that the consumer is present to login to their bank. The data is afterwards available to generate reports.

A successfully finished flow returns a consumer identifier and the available account identifiers for this consumer. These IDs will be needed later to specify the consumer/account for which a report should be generated.

To check if this flow was finished successfully, the client backend server needs to call the flow-finished endpoint.

Request Body Structure of an Insights Flow

{
    "intended_reports" : ?Array<IntendedReport>,
    "refresh_days": ?Integer,
    "from_date": ?Date,
    "to_date": ?Date,
    "accounts" : ?RefreshFlowAccounts,
    "insights_consumer_id" : ?String,
    "data_retention_minutes" : ?Integer,
    "store_consent": ?Enum<'NO', 'REQUIRED', 'OPTIONAL'>,
    "allowed_accounts": ?AllowedAccounts   
}

intended_reports IntendedReport[], optional

The intended_reports specifies which reports should later be generated with the extracted data. Using this property reduces the amount of data that is extracted form the consumers account. As default data for all available reports are extracted.

refresh_days Integer, optional

If refresh_days is specified the parameters from_date and to_date will be derived from current day (today) minus the given number of days.

The timeframe for which the data should be refreshed can be set by specifying either the from_date and to_date parameters or the refresh_days parameter. If no timeframe is specified, the default timeframe of the last 62 days will be used.

from_date Date (String: "YYYY-MM-DD"), optional

The from_date property (in combination with the to_date property) will be used as the start date for the account information to be retrieved.

The timeframe for which the data should be refreshed can be set by specifying either the from_date and to_date parameters or the refresh_days parameter. If no timeframe is specified, the default timeframe of the last 62 days will be used.

to_date Date (String: "YYYY-MM-DD"), optional

The to_date property (in combination with the from_date property) will be used as the end date for the account information to be retrieved.

The timeframe for which the data should be refreshed can be set by specifying either the from_date and to_date parameters or the refresh_days parameter. If no timeframe is specified, the default timeframe of the last 62 days will be used.

The timeframe (combination of from_date and to_date or the refresh_days) for the flow must be within the timeframe defined at the session start, see here.

Some banks limit the transactions to specific time frames, e.g. only the last 90 days from today. If the requested time frame is not supported we either adjust it and extract the available transactions or return an error. The adjusted timeframe is returned in the response.

accounts RefreshFlowAccounts, optional

Defines the accounts of which data will be refreshed. If this property is not set the consumer is asked to select one account similar to setting the accounts.type to CONSUMER_SELECTED.

insights_consumer_id String, optional

This insights_consumer_id will be used to identify a consumer and all data retrieved in this flow will be assigned to this consumer. Any string with less than 128 characters can be used to identify the consumer. If left empty, a new identifier will be generated and returned in the response to this call. If the accounts parameter will select accounts via their respective insights_account_id the insights_consumer_id must be set.

data_retention_minutes Integer, optional

The number of minutes that the data are stored. Default is 10 minutes.

store_consent Enum, optional

The store_consent flag configures if the consent related to the account should be received and stored:

  • choose NO to not store the consent. This is the default value.
  • choose REQUIRED to store the consent and fail if no consent is available. A reason for no consent to be available is if there is no PSD2 connection used for the specific bank.
  • choose OPTIONAL to try to store the consent flag and not fail if it is not available.

allowed_accounts AllowedAccounts, optional

A configuration to filter the fetched account list.

RefreshFlowAccounts

{
    "type": ?Enum<'ALL', 'PRESELECTED', 'REFRESH_KNOWN_ACCOUNTS', 'CONSUMER_SELECTED', 'CONSUMER_MULTI_SELECTED_ADD_ONLY_NEW'>
    "selected_accounts": ?Array<{
        "iban": ?String,
        "account_number": ?String,
        "insights_account_id": ?String,
        "account_id": ?String
    }>,
    "accounts_group_id": ?String
}

type Enum, optional

Defines which accounts should be refreshed:

  • ALL: No consumer interaction, data for all bank accounts that will be available in the session will be refreshed.
  • PRESELECTED: No consumer interaction, the data of accounts defined through the selected_accounts-field will be refreshed.
  • REFRESH_KNOWN_ACCOUNTS: No consumer interaction, refreshes all accounts that are already stored for the consumer that is identified by the given insights_consumer_id.
  • CONSUMER_SELECTED: The consumer is asked to select one of the accounts that is available in the session.
  • CONSUMER_MULTI_SELECTED_ADD_ONLY_NEW: The consumer is asked to select one or multiple accounts to be stored, so accounts that are already stored for the consumer will be filtered out.

The default value is CONSUMER_SELECTED.

accounts_group_id String, optional

All accounts from this account group are preselected. The type needs to be set to PRESELECTED.

The accounts_group_id for specific accounts can be retrieved via the ACCOUNT_INFO report or the accounts-list endpoint.

selected_accounts SelectedAccount[], optional

In case only some accounts of the consumer should be refreshed, this property should be used.

Exactly one of the fields must be set and it must be the same field for all SelectedAccount-objects. E.g. if the iban is set, all other SelectedAccount-objects also must have the iban set.

selected_accounts.iban String, optional

The IBAN of the account to be refreshed.

selected_accounts.account_number String, optional

The account number of the account to be refreshed.

selected_accounts.insights_account_id String, optional

The insights_account_id of the account to be refreshed. The corresponding insights_consumer_id is required in the Insights Flow.

selected_accounts.account_id String, optional

The account identifier, as provided in the result of an accounts flow.

Response Structure of a successful Flow

{
    "data": {
        "state" : Enum<'PROCESSING', 'CONSUMER_INPUT_NEEDED', 'ABORTED', 'EXCEPTION', 'FINISHED'>,
        "result" : ?{
            "type" : Enum<'error', 'insights_refresh'>,
            "accounts" : Array<RefreshFlowResponseAccount>,
            "insights_consumer_id" : String,
            "store_consent_result": Enum<'NOT_STORED', 'STORED'>,
            "category" : ?String,
            "message" : ?String
        }
    }
}

state String, always present

The state property holds the current state of the flow. Find a more detailed description here

result Object, optional

The result property holds the data returned by the Insights-Refresh flow.

result.type String, always present

For successful flows the type property always holds the value insights_refresh.

result.accounts RefreshFlowResponseAccount[], always present

The accounts will be a list of type RefreshFlowResponseAccount, listing the available accounts to generate reports from.

result.insights_consumer_id String, always present

The retrieved data was stored with this insights_consumer_id. It can be used to identify this consumer when generating a report later.

result.message String, optional

If the state is EXCEPTION this property can contain an error message

result.category String, optional

If the state is EXCEPTION this property can contain an error category

result.store_consent_result Enum, always present

Shows if the consent related to this account was stored or not.

RefreshFlowResponseAccount

{
    "insights_account_id": String,
    "iban": ?String,
    "account_id": ?String,
    "from_date": ?Date,
    "to_date": ?Date
}

insights_account_id String, always present

The Account Insights Id of this account, use to create reports or do future refreshs.

iban String, optional

The IBAN of this account. Only present if set in the request accounts.selected_accounts.iban.

account_id String, optional

The account id of this account, Only present if set in the request accounts.selected_accounts.account_id.

from_date Date (String: "YYYY-MM-DD"), optional

The start date of the timeframe for which the transactions were extracted for this account.

to_date Date (String: "YYYY-MM-DD"), optional

The end date of the timeframe for which the transactions were extracted for this account.

Example Response for a successful Insights Flow

{    

  "data": {
    "state": "FINISHED",
    "result": {
      "type": "insights_refresh",
      "accounts": [
        {
          "insights_account_id": "8ed4ac35-04b0-4c4f-a283-41b6e387c422",
          "from_date": "2021-08-01",
          "to_date": "2021-09-30"
        }
      ],
      "insights_consumer_id": "3dbd396b-f8ef-4ab6-9cd8-c5426eafb212"
    }
  }
}

results matching ""

    No results matching ""