Authorization

Use the access_token from the previous step as a Bearer token in all requests.

Authorization: Bearer {access_token}

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

List accounts

GET /rest/accounts/

Returns all financial accounts the user connected during the Widget flow.

Response:

{
  "accounts": [
    {
      "account_id": "A57291.1",
      "iban": "DE89370400440532013000",
      "bic": "COBADEFFXXX",
      "account_number": "0532013000",
      "bank_code": "37040044",
      "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"
        }
      },
      "auto_sync": false,
      "is_jointly_managed": false,
      "supported_payments": {
        "SEPA transfer": {
          "can_be_recurring": false,
          "can_be_scheduled": false,
          "max_purpose_length": 140
        }
      },
      "status": {
        "synced_at": "2025-06-01T08:14:22.000Z",
        "succeeded_at": "2025-06-01T08:14:22.000Z"
      }
    }
  ]
}

Key account fields

List transactions

GET /rest/transactions

Returns the full transaction history for the user's connected accounts, including nrich enrichment data (categories and payment partners).

Query parameters:

Parameter	Description
`account_id`	Filter to a specific account.
`since`	Return transactions from this date (ISO 8601).
`until`	Return transactions up to this date (ISO 8601).

Response:

{
  "transactions": [
    {
      "transaction_id": "T57291.184",
      "account_id": "A57291.1",
      "amount": -12.99,
      "currency": "EUR",
      "iban": "SE3550000000054910000003",
      "bic": "ESSESESS",
      "name": "SPOTIFY AB",
      "purpose": "SVWZ+Spotify Abo 55912837 EREF+SPOTISP1234567",
      "booking_text": "Lastschrift",
      "sepa_purpose_code": "GDDS",
      "creditor_id": "SE59ZZZ0000017491",
      "mandate_reference": "SPOTIFY-DE-923847102",
      "end_to_end_reference": "SPOTISP1234567",
      "type": "Direct Debit",
      "booked": true,
      "booked_at": "2025-05-28T00:00:00.000Z",
      "settled_at": "2025-05-28T00:00:00.000Z",
      "categories": [
        { "id": 22, "parent_id": null, "name": "Leisure" },
        { "id": 33, "parent_id": 22, "name": "Music streaming" }
      ],
      "payment_partner": {
        "id": "c9944518e86e46409e46a52b0f55dee0",
        "name": "Spotify AB"
      }
    },
    {
      "transaction_id": "T57291.185",
      "account_id": "A57291.1",
      "amount": 2850.00,
      "currency": "EUR",
      "iban": "DE12500105170648489890",
      "bic": "BELADEBEXXX",
      "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"
  }
}

Key transaction fields

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