Categorisation and Insights API Documentation

Introduction

Glossary

Authentication

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:

Versioning

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.

Error Handling

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:

[
    {
        "title": "Not Found",
        "detail": "The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.",
        "error-code": "NOT_FOUND",
        "source": []
    }
]

HTTP code 404

Possible error codes

Webhooks

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:

{
  "request_id": "request_id",
  "status": "COMPLETE/FAILURE",
}

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:

{
  "client_id": "",
  "client_secret": "",
  "audience": " (can be null)",
  "grant_type": "client_credentials"
}

The expected response:

{
    "access_token": "",
    "expires_in": 86400,
    "token_type": "Bearer"
}

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.

Supported File Formats

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.

Default JSON Input File Structure

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.

{
    "account_list": [
        {
            "account_nr": "GB29IBAN20160604201923",
            "holder_name": "Alex Watson",
            "holder_id": "920160406",
            "bank_name": "Some Bank",
            "currency": "GBP",
            "start_balance": 2016.46,
            "end_balance": 2750.86,
            "debit_turnover": 366.40,
            "credit_turnover": 1100.80,
            "period_start": "2019-08-01",
            "period_end": "2019-08-15",
            "transaction_list": [
                {
                    "date": "2019-08-01",
                    "partner": "Local Groceries",
                    "info": "PURCHASE 201620190406111 15.45GBP",
                    "transaction_id": "arbritary-unique-id1",
                    "sum": -15.45
                },
                {
                    "date": "2019-08-05",
                    "partner": "Job Ltd",
                    "info": "SALARY 201620190406222 900.80GBP",
                    "transaction_id": "arbritary-unique-id2",
                    "sum": 900.80
                },
                {
                    "date": "2019-08-07",
                    "partner": "Freelance Agency Ltd",
                    "info": "ROYALTIES 201620190406333 200.00GBP",
                    "transaction_id": "arbritary-unique-id3",
                    "sum": 200.00
                },
                {
                    "date": "2019-08-11",
                    "partner": "Gas Station",
                    "info": "PURCHASE 201620190406444 50.45GBP",
                    "transaction_id": "arbritary-unique-id4",
                    "sum": -50.45
                },
                {
                    "date": "2019-08-15",
                    "partner": "Loan Bank",
                    "info": "MORTGAGE PAYMENT, AGREEMENT A201664 300.50GBP",
                    "transaction_id": "arbritary-unique-id5",
                    "sum": -300.50
                }
            ]
        }
    ]
}

Bank Statements from Third Parties

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.

Coverage and Country Codes

See below the full country list and their respective country codes. PI means private individual transactions and SME means enterprise transactions. Please note that countries that aren't fully calibrated are supported, but for the initial file upload you might experience lower than than average categorisation results. A re-upload of the same file after 24h from the initial upload is expected to produce satisfactory quality categorisation and insights.

Product customisation via params argument

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.

Response Metadata

Some products will return metadata in API response describing what variables were used analysing given statement(s).

Statement details

Statement details metadata is returned by all products.

{
    "data": {
        "attributes": {
            ...,
            "metadata": {
                "statement-details": {
                    "count_of_analysed_accounts": 1,
                    "count_of_uploaded_accounts": 2,
                    "drop_joint_accounts": true,
                    "drop_shared_accounts": true
                }
            },
            "status": "completed"
        },
        "type": "report processing status"
    }
}
            

Insights details

Insights details metadata is returned by Income, Loans and Risk products.

{
  "data": {
    "attributes": {
      "metadata": {
        "insights-details": {
          "currency": {
            "display_currency":"EUR",
            "applied_currency_conversions": [
              {
                "currency": "AUD",
                "rate":0.62
              },
              {
                "currency": "PLN",
                "rate":0.22
              }
            ]
          }
        }
      },
      "status": "completed"
    },
    "type": "report processing status"
  }
}