Introduction
request_id
;null
value.Nordigen API uses token-based authentication. You'll need the client_id
and client_secret
assigned to your organisation. These credentials can be found in the Nordigen API Dashboard. To get the token, send the request to https://api.nordigen.com/oauth/token with POST HTTP request body:
KEY | VALUE | OPTIONAL |
---|---|---|
client_id | Your client ID | |
client_secret | Your client secret | |
audience | https://nordigen/api | |
grant_type | client_credentials |
We periodically release new versions. Current version is v2. You can provide specific version in the request URL; e.g. https://api.nordigen.com/v2/report/process/:request-id
.
All error HTTP codes are going to be 4xx or 5xx, so we recommend using success http codes for the control flow and the error codes for informative purposes. If an error has occurred, it will be displayed in the following form:
Possible error codes
Error code | Description | HTTP status |
---|---|---|
API_REQUIRED_PARAMS_MISSING | One or more params required missing, check source for which elements need to be filled | 400 |
TIMEOUT_PROCESSING | Processing timed out | 400 |
ANALYSIS_ALREADY_REQUESTED | Analysis operations were already requested for this record | 400 |
PDF_PARSE_FAILURE | Unsupported pdf file was uploaded | 400 |
RATE_LIMIT | Too many requests in a short period of time | 429 |
EXCEEDED_LIMIT | Processing record limit has been exceeded | 400 |
NO_SUITABLE_PARSERS | Unsupported file was uploaded but with valid file format | 400 |
UNKNOWN_ERROR | Unexpected error occurred whilst processing the file | 500 |
NOT_FOUND | Could not find specified request_id in database | 404 |
GONE | Stored file associated with the request_id can not be fetched | 410 |
UNSUPPORTED_COUNTRY_REQUESTED | Given country code not in supported country list, see Supported File Formats | 400 |
SERVICE_UNAVAILABLE | Downtime/misconfiguration on Nordigen part | 503 |
FORBIDDEN | No access for the resource | 403 |
FEATURE_EXTRACT_FAILURE | Failed process feature extraction, most likely because of the lack of data | 400 |
CREDIT_SCORING_FAILURE | Failed process credit scoring calculation, most likely because of the lack of data | 400 |
Set up webhooks to send a request with the status of the processing record to your server once analysing account information is finished.
Setup
To set up webhooks see Webhooks under Endpoints section. To apply the webhook, pass "use_webhook": true
when requesting which operations to use.
Webhook request body
To the specified URL POST, the request will be sent with body as follows:
Authentication
We support OAuth 2.0 and Basic Auth flows. If Oauth 2.0 is set, a token POST request will be sent with body as follows:
The expected response:
If a webhook request responds with 401, a new token will be requested once.
Retries
For HTTP codes 413, 429, 500, 502, 503, 504 the webhook request will be retried up to 10 times with exponential backoff of 0.5 * (2^n-1)
, where n is a retry count.
The system accepts account information in the following file formats: JSON (most popular), XML and PDF (see the list below for more details). Image files (including scanned bank statements, etc.) are not supported at this time.
Our products currently support 19 markets (see the list below for more details). If our products do not support a country of your interest, please contact us.
Only UTF-8 character encoding supported. Characters not fitting the standard will be replaced as unrepresentable.
When uploading account information to Nordigen API, always make sure that your files have the correct data structure. Please note that some keys in the input files are optional; namely, the key value can be empty. You can download a sample of our default JSON input file here.
KEY | DESCRIPTION | OPTIONAL |
---|---|---|
account_nr | IBAN | Yes |
holder_name | Name of the account holder | Yes |
bank_name | Name of the bank the account belongs to | Yes |
currency | A string of currency objects | Yes |
start_balance | Account balance at the beginning | Yes |
end_balance | Account balance after all the transactions | Yes |
debit_turnover | The amount of money gained since the first transaction until the last one | Yes |
credit_turnover | The amount of money spent since the first transaction until the last one | Yes |
period_start | Date of the first transaction | Yes |
period_end | Date of the last transaction | Yes |
transaction_list | A list of transaction objects | |
date | Transaction's date field | |
partner | Transaction's counterparty name field (e.g. the company's name where you made the purchase from) | |
info | Transaction's description field | |
transaction_id | Transaction's ID | Yes |
sum | The amount of money earned/spent |
Nordigen supports the default account information outputs from a list of major open banking providers. If you use a third party open banking provider to access bank account information, please see the list of supported file formats below. In case you cannot find your file format among the supported formats, please transform your data to the default JSON input file format.
Country | Format | Provider |
---|---|---|
* | asice | * |
* | bdoc | * |
* | json | Nordigen, Kevin |
AU | json | Credit Sense, Proviso |
AU | xml | Yodlee |
CZ | xml | Kontomatik |
DE | json | Arvato, FintecSystems |
DK | xml | Instantor |
EE | xml | Kontomatik |
EE | Coop Pank, Danske, LHV, Luminor, Nordea, SEB, Swedbank | |
ES | json | Instantor |
ES | xml | Instantor, Kontomatik |
FI | json | Instantor, Tink |
FI | xml | Instantor |
FI | Aktia, Danske, Nordea, Pohjola | |
GB | json | Tink |
ID | json | Instantor |
LT | DNB, Luminor, SEB, Swedbank | |
LV | json | Instantor |
LV | xml | Kontomatik |
LV | Citadele, DNB, Luminor, Nordea, Norvik, PNB, PrivatBank, SEB, Swedbank, VSAA | |
NZ | json | Proviso |
PL | xml | Kontomatik |
SE | json | Instantor, Tink |
SE | xml | Instantor |
Nordigen system is now calibrated for 19 countries in total. Below you can see the list of these countries and their respective country codes. Please note that whenever you are using Nordigen products via API, the country code must be passed in lower case.
When calling apply operations to uploaded account data endpoint its possible to customise how these products will be calculated. This can be done by sending params
inside the request body. Some of these customisation parameters are product specific and they will be described on the respective product documentation page, in this section You can read about generic customisation params that work for all products.
Key | Type | Description | Applicable products |
---|---|---|---|
drop_shared_accounts | Boolean | If account is identified as shared, exclude it from analysing | * |
drop_joint_accounts | Boolean | If account is identified as joint, exclude it from analysing | * |
period | Integer | Count of calendar months that should be subsetted for calculations. Default period is all available calendar months of uploaded statement | Income, Loans, Risk |
currency | String | Three letter code (ISO-4217) of main currency for output values. Default currency is the main currency of the statement’s country | Income, Loans, Risk |
Some products will return metadata in API response describing what variables were used analysing given statement(s).
Statement details metadata is returned by all products.
Key | Type | Description |
---|---|---|
count_of_analysed_accounts | Integer | Count of how many accounts were used as input for requested products |
count_of_uploaded_accounts | Integer | Count of how many accounts were given in input |
drop_joint_accounts | Boolean | Was the system set to ignore joint accounts |
drop_shared_accounts | Boolean | Was the system set to ignore shared accounts |
Insights details metadata is returned by Income, Loans and Risk products.
Key | Type | Description |
---|---|---|
display_currency | String | Currency that is used when calculating output |
applied_currency_conversions | Integer | Currencies that were present in input transactions and with what rate they were converted to display currency |