Consent Insights Refresh

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:

  • Starting the Consent Insights Refresh
  • Getting the result of the started refresh

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.

POST /insights/v1/consents/insights-refresh HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Bearer <Token>
Host: <Host>
{
    "consent_id": ?string,
    "consent_token": ?string,
    "insights_consumer_id" : ?string,    
    "intended_reports" : ?Array<IntendedReport>,
    "refresh_days": ?int,
    "from_date": ?Date,
    "to_date": ?Date,
    "accounts" : ConsentAccounts,
    "data_retention_minutes" : ?int,
    "psu": ?{
        "user_agent": string,
        "ip_address": string,
    }
}

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. It has to be provided in the YYYY-MM-DD format according to ISO 8601.

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. It has to be provided in the YYYY-MM-DD format according to ISO 8601.

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.

accounts ConsentAccounts, required

There are 2 scenarios:

  1. accounts with empty IDs and IBANs and its all property is true: All accounts of the consumer will be used for the refresh.
  2. accounts contains IDs or IBANs and its all property is false (or not set): Only the given accounts will be refreshed.

Other combinations will result in validation errors.

data_retention_minutes int, 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.

ConsentAccounts

{
    "all": boolean,
    "selected_accounts": Array<{
        "iban": ?string,
        "insights_account_id": ?string,
        "account_id": ?string
    }>
}

all boolean, required

If this property is set to true, the list of selected_accounts-property must be empty.

selected_accounts SelectedAccount[], required

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: Bearer <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": ?[
                {
                    "insights_account_id": string
                }
            ]
        },
        "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
}

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.

{
    "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"
                }
            ]
        },
        "consent_token": "eyJhbG123451NiJ9.eyJ212345uIjoiMS4xIiwiY29uc2VudF9pZCI6InVmMDNua284N2swc2I1b29qYWh1YWJ0NGFuNTZlMTIyI123452l"
    }
}

results matching ""

    No results matching ""