The Consent Insights Refresh endpoint differs from most other consent endpoints because depending on factors like the used bank, the account size and the intended reports it can take longer time to complete the refresh. To make this process more robust it is split into two parts:

The Insights API supports storing of consent. This way the consent for accounts don't have to be received via the fetch consent token endpoint but instead are saved on Klarnas side. This way a client can start a Consent Insights Refresh without providing the consent-id and consent-token. The consent must be stored during the Insights-Refresh flow as described here.

PUT /insights/v1/consents/insights-refresh HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Token <Token>
Host: <Host>

{
    "consent_id": ?String,
    "consent_token": ?String,
    "insights_consumer_id" : ?String,    
    "intended_reports" : ?Array<IntendedReport>,
    "refresh_days": ?Integer,
    "from_date": ?Date,
    "to_date": ?Date,
    "accounts" : ConsentAccounts,
    "data_retention_minutes" : ?Integer,
    "psu": ?{
        "user_agent": String,
        "ip_address": String,
    },
    "allowed_accounts": ?AllowedAccounts
}

consent_id String, optional

The consent_id to use for the consent calls to refresh the consumers data. This field must not be set if a previously stored consent should be used.

consent_token String, optional

The consent_token to use for the consent calls to refresh the consumers data. This field must not be set if a previously stored consent should be used.

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. This parameter is required if stored consents should be used. Also if the accounts parameter will select accounts via their respective insights_account_id the insights_consumer_id must be set.

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.

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 (combination of from_date and to_date or the refresh_days) for the refresh 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 ConsentAccounts, required

Defines the accounts of which data will be refreshed.

data_retention_minutes Integer, optional

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

psu Object, optional

The psu object is optional, however, if the consumer is present, it is recommended to provide it. Some banks soften their daily consent usage restrictions if the PSU data is available.

psu.user_agent String, required

The user_agent property holds the user agent string of the consumer's client application, e.g. the web browser.

psu.ip_address String, required

The ip_address property holds the IP address of the consumer. Both IPv4 and IPv6 are accepted formats.

allowed_accounts AllowedAccounts, optional

A configuration to filter the fetched account list.

ConsentAccounts

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

type Enum, required

Defines which accounts should be refreshed:

ALL: Data for all bank accounts that will be available with this consent will be refreshed.
PRESELECTED: The data of accounts defined through the selected_accounts-field will be refreshed.
REFRESH_KNOWN_ACCOUNTS: Refreshes the accounts that are already stored for the consumer that is identified by the given insights_consumer_id.

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.insights_account_id String, optional

The Account Insights UUID of the account to be refreshed.

selected_accounts.account_id String, optional

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

{
    "data": {
        "refresh_id": String,
        "self": String,
        "state": Enum<'PROCESSING', 'FINISHED', 'EXCEPTION'>
    }
}

refresh_id String, always present

The refresh id.

self String, always present

The url to this refresh. Can be called to receive the status of the refresh. This call is described below.

state Enum, always present

The state property holds the current state of the consent refresh.

Request the refresh status

POST <data.self> HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Token <Token>
Host: <Host>

The url is taken from the start response.

Response for the refresh status

{
    "data": {
        "refresh_id": String,
        "self": String,
        "state": Enum<'PROCESSING', 'FINISHED', 'EXCEPTION'>
        "result": ?{
            "type": String,
            "insights_consumer_id": ?String,
            "category" : ?String,
            "message" : ?String,
            "accounts": ?Array<ConsentRefreshResponseAccount>
        },
        "consent_token": ?String
    }
}

refresh_id String, always present

The refresh id.

self String, always present

The url to this refresh. Can be called to receive the status of the refresh.

state Enum, always present

The state property holds the current state of the consent refresh.

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 ConsentRefreshResponseAccount[], optional

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

result.insights_consumer_id String, optional

The retrieved data was stored with this insights_consumer_id. It can be used in later calls to identify this consumer.

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.consent_token String, optional

The new consent_token that must be used for the next consent calls. This property is not set for refreshs that use a stored consent.

ConsentRefreshResponseAccount

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

insights_account_id String, always present

The Account Insights UUID of this account, used 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 requestaccounts.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.

{
    "data": {
        "refresh_id": "b7812345-91b8-48fe-ac2a-fe76adcc24d1",
        "self": "https://api.openbanking.playground.klarna.com/insights/v1/consents/insights-refresh/b7812345-91b8-48fe-ac2a-fe76adcc24d1/get",
        "state": "FINISHED",
        "result": {
            "type": "insights_refresh",
            "insights_consumer_id": "5a012345-7560-4f71-9339-123452ec690d",
            "accounts": [
                {
                    "insights_account_id": "52612345-3be3-40ec-9736-12345358de67",
                    "from_date": "2021-08-01",
                    "to_date": "2021-09-30"
                }
            ]
        },
        "consent_token": "eyJhbG123451NiJ9.eyJ212345uIjoiMS4xIiwiY29uc2VudF9pZCI6InVmMDNua284N2swc2I1b29qYWh1YWJ0NGFuNTZlMTIyI123452l"
    }
}

Insights-Refresh

ConsentAccounts

Request the refresh status

Response for the refresh status

ConsentRefreshResponseAccount

results matching ""

No results matching ""

Consent Insights Refresh

Storing the consent

Starting the Consent Insights Refresh

ConsentAccounts

Response Structure of a started Consent Insights Refresh

Request the refresh status

Response for the refresh status

ConsentRefreshResponseAccount

Example Response for a status call of a successful Consent Insights Refresh

results matching ""

No results matching ""