Categorisation Quickstart Guide

This document explains how to jump start your integration with the Nordigen API.

Step 1: Getting Access Token

First you'll need to get your client_id and client_secret from the Nordigen API Dashboard. Run this command in the terminal (NB: make sure you change YOUR_ID and YOUR_SECRET with the ones you got from the Dashboard):

curl -X POST \
https://api.nordigen.com/oauth/token \
-H 'Content-Type: application/json' \
-d '{
  "grant_type": "client_credentials",
  "client_id": "YOUR_ID",
  "client_secret": "YOUR_SECRET",
  "audience": "https://nordigen/api"
}'

The response you'll receive after running the command given above:

{
    "access_token": "YOUR_ACCESS_TOKEN",
    "expires_in": time after which token expires in seconds,
    "token_type": "Bearer"
}

HTTP code: 200

Step 2: Getting Request ID

Download the example.json file and save it in the directory from which you are making the request. Run this command (NB: change YOUR_ACCESS_TOKEN with the one you got in the previous response):

curl -X POST \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-F input=@example.json \
https://api.nordigen.com/v2/report

In response you'll get:

{
    "data": {
        "attributes": {
            "available-operations": [
                "categorisation",
                "insights-income",
                "insights-loans",
                "insights-risk",
                "simple-score"
            ],
            "request-id": "162d7bb2-855c-477d-ad39-fd43fec5c44a",
            "status": "completed"
        },
        "relationships": {
            "operations": {
                "links": {
                    "related": "https://api.nordigen.com/v2/report/process/162d7bb2-855c-477d-ad39-fd43fec5c44a",
                    "self": "https://api.nordigen.com/v2/report"
                }
            }
        },
        "type": "report pre-processing record"
    }
}

HTTP code 202

Step 3: Making a Request

Change YOUR_ACCESS_TOKEN with the one you got in response after completing Step 1; change REQUEST_ID with the one you got in the previous response after completing Step 2, and run this command (NB: each upload that you process has its unique REQUEST_ID):

curl -X PUT \
https://api.nordigen.com/v2/report/process/REQUEST_ID \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "operations": ["categorisation"],
  "country": "uk"
}'

In response you'll receive:

{
    "data": {
        "attributes": {
            "request-id": "2bd32dc8-2c59-4a06-8892-63c62a23fe35",
            "status": "queued"
        },
        "relationships": {
            "result": {
                "links": {
                    "related": "https://api.nordigen.com/v2/report/2bd32dc8-2c59-4a06-8892-63c62a23fe35",
                    "self": "https://api.nordigen.com/v2/report/process/162d7bb2-855c-477d-ad39-fd43fec5c44a"
                }
            }
        },
        "type": "report processing record"
    }
}

HTTP code 202

Step 4: Getting Results

Change YOUR_ACCESS_TOKEN with the one you used in the previous request and REQUEST_ID with one you got in previous response, and run this command:

curl -X GET \
https://api.nordigen.com/v2/report/REQUEST_ID \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

In response you'll get a categorised account information:

{
    "data": {
        "attributes": {
            "categorisation": {
                "accounts": [
                    {
                        "account_number": "GB29IBAN20160604201923",
                        "bank": "Imperial Bank",
                        "country": "uk",
                        "currencies": [
                            {
                                "code": "GBP",
                                "credit_turnover": 1000.0,
                                "debit_turnover": 1000.0,
                                "end_balance": 2750.86,
                                "start_balance": 2016.46,
                                "transactions": [
                                    {
                                        "amount": -15.45,
                                        "category_id": 84,
                                        "title": "Income from rent",
                                        "date": "2019-08-01",
                                        "info": "PURCHASE 201620190406111 15.45GBP",
                                        "transaction_id": "unique-id-1",
                                        "partner": "Local Groceries"
                                    },
                                    {
                                        "amount": 900.8,
                                        "category_id": 85,
                                        "title": "Salary",
                                        "date": "2019-08-05",
                                        "info": "SALARY 201620190406222 900.80GBP",
                                        "transaction_id": "unique-id-2",
                                        "partner": "Job Ltd"
                                    },
                                    {
                                        "amount": 200.0,
                                        "category_id": 23,
                                        "title": "Unknown"
                                        "date": "2019-08-07",
                                        "info": "ROYALTIES 201620190406333 200.00GBP",
                                        "transaction_id": "unique-id-3",
                                        "partner": "Freelance Agency Ltd"
                                    },
                                    {
                                        "amount": -50.45,
                                        "category_id": 44,
                                        "title": "Fuel",
                                        "date": "2019-08-11",
                                        "info": "PURCHASE 201620190406444 50.45GBP",
                                        "transaction_id": "unique-id-4",
                                        "partner": "Gas Station"
                                    },
                                    {
                                        "amount": -300.5,
                                        "category_id": 81,
                                        "title": "Other loans",
                                        "date": "2019-08-15",
                                        "info": "MORTGAGE PAYMENT, AGREEMENT A201664 300.50GBP",
                                        "transaction_id": "unique-id-5",
                                        "partner": "Loan Bank"
                                    }
                                ]
                            }
                        ],
                        "holders": [
                            {
                                "name": "Alex Watson"
                            }
                        ],
                        "is_joint_ownership": false,
                        "is_shared_ownership": false,
                        "period_end": "2019-08-15",
                        "period_start": "2019-08-01"
                    }
                ],
                "category_tree_version": null
            },
            "status": "completed"
        },
        "type": "report processing status"
    }
}

HTTP code 200