Onetime Income Report

post

https://api.finx-s.qwist.cloud/onetime/income-report

Create a widget link to initiate the income report generation.

Body Params

state

string

A client-provided identifier that helps track a specific user's journey through the widget flow. When you initially create the widget session, you can set this value to any string that helps identify the user's context (e.g., a session ID, user ID, or transaction reference). When the user completes their interaction and is redirected back to your redirect_uri, this same state value is returned as a query parameter. This mechanism allows you to securely match the returning user with their original session and maintain context about who they are and what they were doing, particularly important in scenarios with multiple concurrent widget sessions.

redirect_uri

url

required

The URL where users will be redirected after completing their interaction with the Widget.

The redirect includes the following query parameters:

state: Your original state value passed during initialization
success: Boolean indicating whether the flow completed successfully
cancel: Boolean indicating if the user canceled the flow (only present when canceled)
code: Authorization code valid for 1 hour, used to obtain an access token (only present on successful completion)
flow_id: Unique identifier for accessing flow-specific resources

language

string

enum

The display language used in the Widget UI.

Allowed:

provider_id

object

Optional identifier to pre-select a specific financial provider, bypassing the provider search and selection step. When omitted, users can search and choose their provider through the Widget UI. To obtain valid provider IDs, refer to the catalog endpoint.

accounts

array of objects

Defaults to

Array of account identifiers (IBANs) that influences both provider selection and account filtering. When provided, the Widget will:

automatically select the financial provider based on the bank code in the IBAN(s), and 2. after successful connection, only select accounts whose account numbers match those specified in the IBAN(s). Important: All provided IBANs must belong to the same bank access/connection, as multiple bank connections cannot be initialized simultaneously. This parameter streamlines the user experience by removing manual provider selection and account choosing steps.

accounts

account_types

array of strings

Defaults to

Restricts which account types users can select during the connection flow. Use this to limit account selection to specific types (e.g., only Giro accounts). When empty, all account types are available for selection.

account_types

allow_multi_selection

boolean

Defaults to true

Controls whether users can select multiple accounts during the connection flow. When set to false, users are limited to selecting a single account. Note:
This setting is ignored if specific accounts are pre-selected using the accounts parameter.

sync_period

integer

Defaults to 90

Specifies the historical data retrieval period in days. The Widget will request the transaction history from the financial provider for this number of days from the current date. Default is 90 days.

Responses

201Widget link created

400Bad request.

401You are not authorized.