Categorisation and Insights API Documentation

Introduction

This document explains how to integrate with Nordigen API to process and analyse account information. Nordigen API is a set of endpoints that allows you to integrate our Transaction Categorisation and Insights solutions with your system. All responses will be shown in JSON format. All endpoints require the Authorization token.

Before you start, make sure you have acquired an API Client ID and Client Secret from the Nordigen Api Dashboard. If you are not a Dashboard user, please contact our support team.

To jump start your integration, head straight to the Quickstart Guide.

If you’re looking for Account Information API documentation, click here.


Glossary

  • Operations: an analysis product to be applied on a processing record;
  • Operation keyword: a keyword that needs to be passed when requesting to apply product(s) to a processing record;
  • Request ID: identification for a processing record;
  • Processing record: uploaded statement(s) in either uploaded, processing, or finished state, identified by its request_id;
  • Category tree: a data structure for holding categories, identified by ID, containing relationship between parent and child categories;
  • Optionality: for each key, it is stated whether this key is optional or not. In this context, optional stands for the possibility to return a null value.

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:

KEYVALUEOPTIONAL
client_idYour client ID 
client_secretYour client secret 
audiencehttps://nordigen/api 
grant_typeclient_credentials 

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

Error codeDescriptionHTTP status
API_REQUIRED_PARAMS_MISSINGOne or more params required missing, check source for which elements need to be filled400
TIMEOUT_PROCESSINGProcessing timed out400
ANALYSIS_ALREADY_REQUESTEDAnalysis operations were already requested for this record400
PDF_PARSE_FAILUREUnsupported pdf file was uploaded400
TOO_MANY_REQUESTSToo many requests in a short period of time429
EXCEEDED_LIMITProcessing record limit has been exceeded400
NO_SUITABLE_PARSERSUnsupported file was uploaded but with valid file format400
UNKNOWN_ERRORUnexpected error occurred whilst processing the file500
NOT_FOUNDCould not find specified request_id in database404
GONEStored file associated with the request_id can not be fetched410
UNSUPPORTED_COUNTRY_REQUESTEDGiven country code not in supported country list, see Supported File Formats400
SERVICE_UNAVAILABLEDowntime/misconfiguration on Nordigen part503
FORBIDDENNo access for the resource403
FEATURE_EXTRACT_FAILUREFailed process feature extraction, most likely because of the lack of data400
CREDIT_SCORING_FAILUREFailed process credit scoring calculation, most likely because of the lack of data400

 


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_id>",
  "client_secret": "<client_secret>",
  "audience": "<audience> (can be null)",
  "grant_type": "client_credentials"
}

The expected response:

{
    "access_token": "<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.


 

Nordigen Open Banking JSON Input File Structure

Nordigen Categorisation & Insights API accepts account data aggregated via Nordigen's Open Banking Portal. The supported format matches Berlin Group standard and files are provided in JSON. To upload multiple accounts at once you can pass the same format into an array of objects described below. In order to process data on customer level with Categorisation & Insights API, please make sure to upload all data points in the format outlined below:

{
  "transactions": {
    "booked": [
      {
        "transactionId": "2020103000624289-1",
        "debtorName": "Alex Watson",
        "debtorAccount": {
          "iban": "GB29IBAN20160604201923"
        },
        "transactionAmount": {
          "currency": "EUR",
          "amount": "45.00"
        },
        "bankTransactionCode": "PMNT",
        "bookingDate": "2020-10-30",
        "valueDate": "2020-10-30",
        "remittanceInformationUnstructured": "A Gift"
      },
      {
        "transactionId": "2020111101899195-1",
        "transactionAmount": {
          "currency": "EUR",
          "amount": "-15.00"
        },
        "bankTransactionCode": "PMNT",
        "bookingDate": "2020-11-11",
        "valueDate": "2020-11-11",
        "remittanceInformationUnstructured": "PAYMENT Tasty Coffe"
      }
    ],
    "pending": [
      {
        "transactionAmount": {
          "currency": "EUR",
          "amount": "10.00"
        },
        "valueDate": "2020-11-03",
        "remittanceInformationUnstructured": "Reserved PAYMENT Best Burgers"
      }
    ]
  },
  "balances": [
    {
      "balanceAmount": {
        "amount": "100.00",
        "currency": "EUR"
      },
      "balanceType": "interimAvailable"
    }
  ],
  "account": {
    "iban": "GB29IBAN20160604201923",
    "currency": "EUR",
    "ownerName": "Alex Watson",
    "bic": "GB29IBAN"
  }
}
KEYDESCRIPTIONOPTIONAL
transactionsArray of transaction objects 
transactionIdUnique transaction identifier given by ASPSPYES
bookingDateThe Date when an entry is posted to an account on the ASPSPs books.YES
valueDateThe Date at which assets become available to the account owner in case of a creditYES
transactionAmountThe amount of the transaction as billed to the account. 
creditorNameName of the creditor if a "Debited" transactionYES
debtorNameName of the debtor if a "Credited" transactionYES
remittanceInformationUnstructuredTransaction description 
bankTransactionCodeBank transaction code as used by the ASPSP and using the sub elements of this structured code defined by ISO20022. For standing order reports the following codes are applicable:
"PMNT-ICDT-STDO" for credit transfers,
"PMNT-IRCT-STDO" for instant credit transfers,
"PMNT-ICDT-XBST" for cross-border credit transfers,
"PMNT-IRCT-XBST" for cross-border real time credit transfers,
"PMNT-MCOP-OTHR" for specific standing orders which have a dynamical amount to move left funds e.g. on month end to a saving account
YES
balancesArray of balance objectsYES
balanceAmountObject describing amount of balance 
balanceTypeType of balance object, currently we only read interimAvailableas balance at the end of the period 
accountobject describing account informationYES
ibanAccount's IBAN codeYES
currencyAccount's currencyYES
ownerNameHolder's nameYES
bicAccoun's BIC codeYES

Nordigen Default JSON Input File Structure

If you're aggregating account data via other Third Party Providers, please make sure to map your result to the default input JSON file structure depicted below. Please note that some keys in the input files are optional; namely, the key value can be empty if not available from data.

You can download a sample of our default JSON input file here. In case of questions about mapping from in house format to Nordigen JSON, please reach out to our support team support@nordigen.com.


{
    "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
                }
            ]
        }
    ]
}
KEYDESCRIPTIONOPTIONAL
account_nrIBANYes
holder_nameName of the account holderYes
bank_nameName of the bank the account belongs toYes
currencyA string of currency objectsYes
start_balanceAccount balance at the beginningYes
end_balanceAccount balance after all the transactionsYes
debit_turnoverThe amount of money gained since the first transaction until the last oneYes
credit_turnoverThe amount of money spent since the first transaction until the last oneYes
period_startDate of the first transactionYes
period_endDate of the last transactionYes
transaction_listA list of transaction objects 
dateTransaction's date field (yyyy-mm-dd) 
partnerTransaction's counterparty name field (e.g. the company's name where you made the purchase from) 
infoTransaction's description field 
transaction_idTransaction's IDYes
sumThe amount of money earned/spent 

 


 

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.

CountryPI Country codeSME Country codeFully calibrated
Austriaatatc 
Australiaauauc
Belgiumbebec 
Bulgariabgbgc 
Brazilbr-
Cypruscycyc 
Czech Republicczczc
Germanydedec
Denmarkdkdkc
Estoniaeeeec
Spainesesc
Finlandfific
Francefrfrc 
Greecegrgrc 
Croatiahrhrc 
Hungaryhuhuc 
Indonesiaid-
Irelandieiec 
Indiain-
Italyititc 
Kazakhstankz-
Lithuanialtltc
Luxembourgluluc 
Latvialvlvc
Maltamtmtc 
Mexicomx-
Netherlandsnlnlc 
Norwaynonoc 
New Zealandnz-
Polandplplc
Portugalptptc 
Romaniaroroc 
Swedensesec
Sloveniasi- 
Slovakiaskskc 
United Kingdomukukc
United States of Americaus-

 


 

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.

KeyTypeDescriptionApplicable products
drop_shared_accountsBooleanIf account is identified as shared, exclude it from analysing*
drop_joint_accountsBooleanIf account is identified as joint, exclude it from analysing*
periodIntegerCount of calendar months that should be subsetted for calculations. Default period is all available calendar months of uploaded statementIncome, Loans, Risk
currencyStringThree letter code (ISO-4217) of main currency for output values. Default currency is the main currency of the statement’s countryIncome, Loans, Risk

 


 

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"
    }
}
      
KeyTypeDescription
count_of_analysed_accountsIntegerCount of how many accounts were used as input for requested products
count_of_uploaded_accountsIntegerCount of how many accounts were given in input
drop_joint_accountsBooleanWas the system set to ignore joint accounts
drop_shared_accountsBooleanWas the system set to ignore shared accounts

 


 

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"
  }
}      
KeyTypeDescription
display_currencyStringCurrency that is used when calculating output
applied_currency_conversionsIntegerCurrencies that were present in input transactions and with what rate they were converted to display currency