Authorization

📘
Before you start
Complete the Implementation Guide to get your access_token and report id.

GET https://api.finx-s.qwist.cloud/rest/risk-reports/{id}

Authorization: Bearer {access_token}

📘
Aggregation scope
All sections except accounts are aggregated across all accounts the user connected. If you need single-account analysis, set allow_multi_selection: false during flow initiation and pass the specific account IBAN.

Full response example

{
  "id": "be844e34-9c73-48dd-8c6b-ef7d67ec991c",
  "period": 12,
  "accounts": [
    {
      "name": "My Giro Account",
      "type": "Giro account",
      "owners": ["Candice Hall"],
      "iban": "DE36590100140000022375",
      "currency": "EUR",
      "is_jointly_managed": false,
      "is_main_account": true,
      "last_transaction_on": "2024-06-25",
      "balance": {
        "days_in_overdraft": 0,
        "average": {
          "one_month": -3419.92,
          "three_months": -32654.87,
          "six_months": -81322.03
        }
      },
      "verification_result": {
        "provided": {
          "name": "Candice Hall"
        },
        "matched": {
          "name": "Candice Hall",
          "affinity": "VERY_HIGH"
        }
      }
    }
  ],
  "income": {
    "summary": {
      "count": 857,
      "total": 475945.40,
      "low": 24432.24,
      "high": 50242.94,
      "average": 39662.12
    },
    "regular": {
      "summary": {
        "count": 34,
        "total": 57700.00,
        "low": 500.00,
        "high": 5200.00,
        "average": 4808.33
      },
      "streams": [
        {
          "count": 22,
          "total": 51700.00,
          "low": 1200.00,
          "high": 3500.00,
          "average": 4308.33,
          "category": { "id": 11, "name": "Income/Revenue" },
          "first_booked_on": "2024-06-03",
          "last_booked_on": "2025-04-05"
        },
        {
          "count": 12,
          "total": 6000.00,
          "low": 500.00,
          "high": 500.00,
          "average": 500.00,
          "category": { "id": 200, "name": "Benefits" },
          "first_booked_on": "2024-05-17",
          "last_booked_on": "2025-04-19"
        }
      ]
    },
    "variable": {
      "summary": {
        "count": 8,
        "total": 3330.21,
        "low": 63.90,
        "high": 907.63,
        "average": 277.52
      },
      "streams": [
        {
          "count": 4,
          "total": 2134.39,
          "category": { "id": 11, "name": "Income/Revenue" },
          "first_booked_on": "2024-06-20",
          "last_booked_on": "2025-04-25"
        }
      ]
    },
    "primary": {
      "count": 11,
      "total": 38500.00,
      "low": 3500.00,
      "high": 3500.00,
      "average": 3208.33,
      "category": { "id": 17, "name": "Wage/Salary" },
      "payment_partner": {
        "id": "922a1f7f-b296-4aa9-8bb8-2c20671fb7dc",
        "name": "Airfreu GmbH"
      },
      "first_booked_on": "2024-06-04",
      "last_booked_on": "2025-04-04",
      "recurrence": "monthly",
      "stability": 0.92
    },
    "risk_indicators": {
      "chargeback": {
        "count": 543,
        "total": 276941.50,
        "average": 23078.46,
        "ratio_to_expenses": 3.29
      },
      "gambling": {
        "count": 87,
        "total": 46639.65,
        "average": 3886.64,
        "ratio_to_expenses": 0.55
      },
      "lottery": {
        "count": 91,
        "total": 46598.41,
        "average": 3883.20,
        "ratio_to_expenses": 0.55
      },
      "refund": {
        "count": 94,
        "total": 44735.63,
        "average": 3727.97,
        "ratio_to_income": 0.53
      }
    },
    "closeness": 18,
    "consumption_ratio": 0.18
  },
  "expenses": {
    "summary": {
      "count": 726,
      "total": -84123.91,
      "low": -8630.66,
      "high": -4851.28,
      "average": -7010.33
    },
    "regular": {
      "summary": {
        "count": 87,
        "total": -17340.40,
        "average": -1445.03
      },
      "streams": [
        {
          "count": 22,
          "total": -14303.08,
          "average": -1191.92,
          "category": { "id": 158, "name": "Rent / Service charges" },
          "first_booked_on": "2024-06-04",
          "last_booked_on": "2025-04-04",
          "ratio_to_income": 0.23
        },
        {
          "count": 12,
          "total": -1324.20,
          "average": -110.35,
          "category": { "id": 149, "name": "Household" },
          "first_booked_on": "2024-05-16",
          "last_booked_on": "2025-04-16",
          "ratio_to_income": 0.02
        }
      ]
    },
    "variable": {
      "summary": {
        "count": 10,
        "total": -575.12,
        "average": -47.93
      },
      "streams": [
        {
          "count": 3,
          "total": -229.46,
          "category": { "id": 98, "name": "Shopping" },
          "first_booked_on": "2024-06-10",
          "last_booked_on": "2024-12-07",
          "ratio_to_income": 0
        }
      ]
    },
    "risk_indicators": {
      "atm": {
        "count": 90,
        "total": -9642.87,
        "average": -803.57,
        "ratio_to_income": 0.02
      },
      "debt_collection": {
        "count": 87,
        "total": -9069.02,
        "average": -755.75,
        "ratio_to_income": 0.02
      },
      "gambling": {
        "count": 89,
        "total": -9486.32,
        "average": -790.53,
        "ratio_to_income": 0.25
      },
      "loan": {
        "count": 363,
        "total": -38010.18,
        "average": -3167.51,
        "ratio_to_income": 0.08
      }
    }
  }
}

Report structure

Section	Description
`id`	Unique identifier for this report.
`period`	The reporting period in months.
`accounts`	Per-account details for each connected account.
`income`	Aggregated income analysis across all accounts.
`income.regular`	Recurring income streams detected over the period.
`income.variable`	Non-recurring incoming transactions.
`income.primary`	The single most significant income stream.
`income.risk_indicators`	Income-side risk signals: chargebacks, gambling winnings, lottery, refunds.
`expenses`	Aggregated expense analysis across all accounts.
`expenses.regular`	Fixed-schedule outgoing payments detected as contracts.
`expenses.variable`	Non-recurring outgoing transactions.
`expenses.risk_indicators`	Expense-side risk signals: ATM withdrawals, debt collection, gambling, loan repayments.

Field reference

accounts - per-account details

income - summary and streams

income.risk_indicators - income-side signals

expenses - regular and variable

expenses.risk_indicators - expense-side signals

Error handling

The nrich API uses standard HTTP status codes and returns a structured error object in the response body.

Error response structure

{
  "error": {
    "code": 1000,
    "group": "client",
    "description": "Request body doesn't match input schema.",
    "data": {
      "redirect_uri": ["Not a valid URL."]
    }
  }
}

Field	Description
`code`	nrich-specific numeric error code.
`group`	Error category: `client`, `user`, `bank`, `general`, or `connectivity`.
`description`	Short human-readable summary.
`data`	Field-level validation details (on `400` errors).

HTTP status codes

Code	Meaning	What to do
`200 OK`	Success.	Parse the response body.
`400 Bad Request`	Invalid or missing parameters.	Check `error.data` for the specific field.
`401 Unauthorized`	Token missing or expired.	Refresh using your `refresh_token` and retry.
`403 Forbidden`	Valid token, insufficient scope.	Verify your credentials have the required scopes.
`404 Not Found`	Resource not found or not yet created.	Confirm the ID is correct; some resources only exist after the user completes the flow.
`423 Resource Locked`	Resource temporarily locked during migration.	Retry with exponential backoff (seconds → minutes).
`500 Internal Server Error`	Unexpected server error.	Retry with backoff; contact support if it persists.

🚧
Implement 423 retry logic
423 can occur after system updates. Your application must handle it with incremental backoff - do not surface it directly to users.

Common nrich error codes

Code	Group	Description
`1000`	client	Invalid request - check `data` for field details
`1002`	client	Entity not found
`1008`	client	Resource busy - implement retry with backoff
`10000`	user	Login credentials are invalid
`10001`	user	PIN is invalid
`10004`	user	TAN is invalid
`10007`	user	PIN change required at the bank
`20000`	bank	Processing at the bank not possible
`20003`	bank	Bank under maintenance
`30000`	general	Processing at nrich not possible
`30005`	general	Task has expired
`40000`	connectivity	Bank not supported