HomeGuidesAPI Reference
Log In
Guides

Implementation Guide

Construct a Qwist Link URL, distribute it to your users, and access the resulting artifacts via the API or the Qwist Console. No backend integration required.

No backend integration required. Qwist Link is a static URL - you construct it once per user and send it to them directly.

📘

No token exchange, no callback URL

Unlike other nrich products, Qwist Link does not require a server-side API call to create a flow. There is no authorization code exchange and no redirect callback to your server. Results are accessed via the API (polling) or using the Qwist Console.

Step 1

Sign up to the Qwist Console and create an application

Step 2

Construct and distribute your Qwist Link

Step 3

Access results programmatically via the API

Step 4

View and download results in the Qwist Console


1. Sign up and create an application

Sign up to the Qwist Console and create an application. Each application is issued a client_id - this is the only credential you need to construct a Qwist Link.

To enable additional reports income-report, risk-report, user-insights) for your application, contact our support team. accounts and transactions are always produced and require no additional configuration.


2. Construct and distribute the link

A Qwist Link is a URL you build by filling in the parameters below - no server-side logic required.

Production:

https://regshield.qwist.cloud/link?client_id={CLIENT_ID}&user_id=USER_ID&language={LANGUAGE}&reporting_period={MONTHS}

Sandbox:

https://api.finx-s.qwist.cloud/link?client_id={CLIENT_ID}&user_id=USER_ID&language={LANGUAGE}&reporting_period={MONTHS}

Example:

https://regshield.qwist.cloud/link?client_id=f2e46016-bde5-462b-b4a3-...&user_id=customer_12345&language=de&reporting_period=12

Parameters

ParameterRequiredDefaultDescription
client_idYes-Your Qwist application identifier, found in the Console.
user_idYes-A stable identifier you choose for this user. Used to find their artifacts in the Console.
languageNoenWidget UI language. Supported: de, en, es, fr, ar.
reporting_periodNo12Months of transaction history to include in generated reports.
📘

Choosing a user_id

Use a stable identifier from your own system - your internal customer ID or email address. This is how you will identify which artifacts belong to which user in the Console. If the same user completes the flow twice with the same user_id, their new artifacts are grouped under the same entry.

Distributing the link

Once constructed, send the link to the user through any channel:

  • As a button or hyperlink on a webpage
  • In a transactional or marketing email
  • In an SMS or messenger message
  • Via a customer portal or chatbot

When the user opens the link, the nrich Widget guides them through bank selection and authentication. After the flow completes, artifacts are generated and become available via the API or in the Console.

🚧

If the user abandons the flow

If a user closes the Widget before completing authentication, no artifacts are generated and they will not appear in the Console. You can re-send the same link at any time. The user_id remains consistent, so any subsequent completion will appear under the same user entry.


3. Access results through the API

Since Qwist Link does not require a backend flow creation call or redirect callbacks, your system retrieves results programmatically using two REST endpoints:

  1. GET /artifact-bundles: Poll to discover which users have completed the flow and inspect their bundle details.
  2. GET /artifact-bundles/{BUNDLE_ID}/artifacts/{ARTIFACT_ID}: Fetch the full data payload (accounts, transactions, or generated reports) for a specific artifact.

Authentication

All API requests require HTTP Basic Authentication using your application credentials from the Qwist Console:

  • Username: Your client_id
  • Password: Your client_secret

Step 3.1: Poll for artifact bundles

You can query /artifact-bundles in two ways: across all users or filtered by a specific user_id.

Option A: Discover which users completed the flow (Batch polling)

If you distribute links to many users and want to check who has completed the flow, call /artifact-bundles without parameters:

GET https://api.finx-s.qwist.cloud/artifact-bundles
Authorization: Basic <credentials>
GET https://regshield.qwist.cloud/artifact-bundles
Authorization: Basic <credentials>

(In production, use https://regshield.qwist.cloud/artifact-bundles)

This returns a list of all artifact bundles belonging to your application, sorted by updated_at descending. Each bundle indicates which user_id completed the flow.

Option B: Check a specific user

If you are waiting for a specific user who was directed to a link, provide their user_id as a query parameter:

GET https://api.finx-s.qwist.cloud/artifact-bundles?user_id=USER_ID
Authorization: Basic <credentials>
GET https://regshield.qwist.cloud/artifact-bundles?user_id=USER_ID
Authorization: Basic <credentials>

ℹ️ You can see the full documentation for this endpoint on the API reference page

Understanding the Bundle Response (200 OK)

If the user completed the flow, the endpoint returns the bundle and its artifact references:

[
  {
    "id": "7f09f0ab-5b0c-4ec7-9ca2-995f50ef7753",
    "user_id": "customer_12345",
    "created_at": "2026-11-12T14:30:00+00:00",
    "updated_at": "2026-11-13T09:15:20+00:00",
    "artifacts": [
      {
        "id": "e62a3571-652e-4f1a-9afa-bda73a48e7e1",
        "type": "accounts",
        "created_at": "2026-11-13T09:15:15+00:00"
      },
      {
        "id": "a17fde7c-3183-492e-91e7-2b359b4abf5e",
        "type": "transactions",
        "created_at": "2026-11-13T09:15:18+00:00"
      },
      {
        "id": "b531dc12-411a-4d92-bb82-628d05178650",
        "type": "accounts",
        "created_at": "2026-11-12T14:30:10+00:00"
      },
      {
        "id": "99ea78ab-1102-4fc9-b690-341e988ad912",
        "type": "transactions",
        "created_at": "2026-11-12T14:30:12+00:00"
      }
    ]
  }
]

If no user has completed the flow yet (or the requested user_id has no completed flows), an empty list is returned.

[]
⚠️

Handling multiple completions for the same user

If a user goes through the Qwist Link periodically or multiple times using the same user_id, their newly generated artifacts are appended to their existing bundle.

As a result:

  • There can be multiple artifacts of the same type (e.g. multiple transactions or accounts entries).
  • Check the bundle's updated_at timestamp to detect if recent activity took place.
  • Check each artifact's created_at timestamp to identify the newest report or retrieve only the entries generated since your last sync.

Step 3.2: Fetch artifact data

Once you have identified the bundle_id and artifact_id you need from the list above, fetch the full data payload using both IDs:

Request:

GET https://api.finx-s.qwist.cloud/artifact-bundles/{bundle_id}/artifacts/{artifact_id}
Authorization: Basic <credentials>
GET https://regshield.qwist.cloud/artifact-bundles/{bundle_id}/artifacts/{artifact_id}
Authorization: Basic <credentials>

ℹ️ The endpoint is documented in the API reference page

Response (200 OK):

{
  "id": "a17fde7c-3183-492e-91e7-2b359b4abf5e",
  "type": "transactions",
  "created_at": "2026-11-13T09:15:18+00:00",
  "meta": {
    "user_id": "customer_12345",
  },
  "raw_result": [
    {
      "account_id": "A1159238363796446009.1",
      "account_number": "1234567896",
      "amount": -0.05,
      "booked": true,
      "booked_at": "2026-04-06T00:00:00+00:00",
      "categories": [
          {
              "id": 233,
              "parent_id": null,
              "name": "Sonstige Ausgaben"
          }
      ],
      "created_at": "2026-11-11T05:00:00.531926+00:00",
      "modified_at": "2026-11-11T05:00:01.459994+00:00",
      "payment_partner": {
          "id": "71ff72df-0adb-491d-8a4a-c8e110d9dbd7",
          "name": "Peter Lustig",
          "confidence": 0.65
      },
      "settled_at": "2026-04-06T00:00:00+00:00",
      "transaction_code": 999,
      "transaction_id": "T1159238363796446009.1",
      "type": "Unknown",
      "external_id": "a1388d51-d9f4-49d2-8b33-6061f25749e0",
      "iban": "DE53900948151234567896",
      "name": "Peter Lustig",
      "currency": "EUR",
      "purpose": "Thanks for Qwist automated payments",
      "bank_code": "90094815",
      "bic": ""
    }
  ]
}

The raw_result field contains the parsed bank data or financial report corresponding to the artifact's type. If an invalid ID is provided or the artifact does not belong to your application, the endpoint returns 404 Not Found. Depending on the artifact type, raw_result can be an array of objects (e.g., for transactions or accounts) or a single JSON object (e.g., for income-report, risk-report). More info on raw_result objects structure can be found in the API reference page


🔒

Client Isolation

Access is strictly isolated per application. You can only view bundles and fetch artifacts that belong to your application's client_id.


4. Access results in the Console

Once a user completes the flow, their artifacts are available in the Qwist Console.

  1. Log in to the Qwist Console.
  2. Open the Qwist Link results section.
  3. Find the user by the user_id you used when constructing the link.
  4. Open their details page to see all generated artifacts.
  5. Download each artifact as JSON.

The artifacts shown reflect your application's configuration. accounts and transactions are always present. Reports appear if they were enabled during onboarding.



Did this page help you?