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 URLUnlike 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.
Sign up to the Qwist Console and create an application
Construct and distribute your Qwist Link
Access results programmatically via the API
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=12Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
client_id | Yes | - | Your Qwist application identifier, found in the Console. |
user_id | Yes | - | A stable identifier you choose for this user. Used to find their artifacts in the Console. |
language | No | en | Widget UI language. Supported: de, en, es, fr, ar. |
reporting_period | No | 12 | Months of transaction history to include in generated reports. |
Choosing auser_idUse 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 flowIf 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_idremains 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:
GET /artifact-bundles: Poll to discover which users have completed the flow and inspect their bundle details.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)
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 userIf 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. multipletransactionsoraccountsentries).- Check the bundle's
updated_attimestamp to detect if recent activity took place.- Check each artifact's
created_attimestamp 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 IsolationAccess 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.
- Log in to the Qwist Console.
- Open the Qwist Link results section.
- Find the user by the
user_idyou used when constructing the link. - Open their details page to see all generated artifacts.
- 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.
Updated 7 days ago
