Authorization

Use the access_token as a Bearer token in all requests. For ongoing access, refresh it using the refresh_token before it expires - no user interaction required.

Authorization: Bearer {access_token}

Base URL: https://api.finx-s.qwist.cloud

List accounts

GET /rest/accounts/

Returns all accounts the user has connected, with current balances and sync status.

Response:

{
  "accounts": [
    {
      "account_id": "A57291.1",
      "iban": "DE89370400440532013000",
      "bic": "COBADEFFXXX",
      "bank_name": "Commerzbank",
      "currency": "EUR",
      "type": "Giro account",
      "name": "Girokonto",
      "owner": "Maria Müller",
      "balance": {
        "balance": 3421.87,
        "balance_date": "2025-06-01T00:00:00.000Z",
        "status": {
          "synced_at": "2025-06-01T08:14:22.000Z",
          "succeeded_at": "2025-06-01T08:14:22.000Z",
          "message": null
        }
      },
      "auto_sync": true,
      "is_jointly_managed": false,
      "status": {
        "synced_at": "2025-06-01T08:14:22.000Z",
        "succeeded_at": "2025-06-01T08:14:22.000Z",
        "message": null
      }
    },
    {
      "account_id": "A57291.2",
      "iban": "DE89370400440532013001",
      "bic": "COBADEFFXXX",
      "bank_name": "Commerzbank",
      "currency": "EUR",
      "type": "Savings account",
      "name": "Tagesgeldkonto",
      "owner": "Maria Müller",
      "balance": {
        "balance": 12500.00,
        "balance_date": "2025-06-01T00:00:00.000Z",
        "status": {
          "synced_at": "2025-06-01T08:14:22.000Z",
          "succeeded_at": "2025-06-01T08:14:22.000Z"
        }
      },
      "auto_sync": true,
      "is_jointly_managed": false
    }
  ]
}

📘
Sync status
Check status.succeeded_at to confirm when data was last successfully refreshed. If succeeded_at differs significantly from synced_at, the last sync attempt may have failed (e.g. the user's bank was temporarily unavailable).

List transactions

GET /rest/transactions

Returns categorised transactions across all connected accounts. nrich enriches each transaction with a spending category and normalised payment partner name.

Query parameters:

Parameter	Description
`account_id`	Filter to a specific account.
`since`	Return transactions from this date (ISO 8601, e.g. `2025-01-01`).
`until`	Return transactions up to this date (ISO 8601).
`booked`	`true` for booked transactions only; `false` for pending only.

Response:

{
  "transactions": [
    {
      "transaction_id": "T57291.184",
      "account_id": "A57291.1",
      "amount": -850.00,
      "currency": "EUR",
      "iban": "DE12345678901234567890",
      "name": "STADTWERKE MÜNCHEN GMBH",
      "purpose": "Rechnung 20250501 KD-NR 48291037",
      "booking_text": "Lastschrift",
      "type": "Direct Debit",
      "booked": true,
      "booked_at": "2025-05-02T00:00:00.000Z",
      "settled_at": "2025-05-02T00:00:00.000Z",
      "categories": [
        { "id": 11, "parent_id": null, "name": "Housing" },
        { "id": 15, "parent_id": 11, "name": "Utilities" }
      ],
      "payment_partner": {
        "id": "stw_muc_001",
        "name": "Stadtwerke München"
      }
    },
    {
      "transaction_id": "T57291.185",
      "account_id": "A57291.1",
      "amount": 2850.00,
      "currency": "EUR",
      "iban": "DE12500105170648489890",
      "name": "ACME GMBH",
      "purpose": "Gehalt Mai 2025 Maria Mueller",
      "booking_text": "Überweisungsgutschrift",
      "type": "Transfer",
      "booked": true,
      "booked_at": "2025-05-30T00:00:00.000Z",
      "settled_at": "2025-05-30T00:00:00.000Z",
      "categories": [
        { "id": 1, "parent_id": null, "name": "Income" },
        { "id": 2, "parent_id": 1, "name": "Salary" }
      ],
      "payment_partner": {
        "id": "a1b2c3d4e5f6",
        "name": "Acme GmbH"
      }
    }
  ],
  "status": {
    "synced_at": "2025-06-01T08:14:22.000Z",
    "succeeded_at": "2025-06-01T08:14:22.000Z"
  }
}

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