Qwist Income Report API

openapi: 3.2.0
info:
  title: nrich Income Report API
  version: '2.10'
  contact:
    name: Qwist GmbH
    email: partnersupport@qwist.com
    url: https://qwist.com
  description: This is the reference for Qwist's nrich API
servers:
- url: https://api.nrich.qwist.cloud
  description: Staging environment
tags:
- name: Income Report
paths:
  /onetime/income-report:
    post:
      summary: Onetime Income Report
      operationId: createOnetimeIncomeReport
      description: Create a widget link to initiate the income report generation.
      tags:
      - Income Report
      security:
      - client_auth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - redirect_uri
              allOf:
              - $ref: '#/paths/~1ongoing~1sync/post/requestBody/content/application~1json/schema/allOf/0'
              - properties:
                  accounts:
                    type: array
                    default: []
                    items:
                      $ref: '#/paths/~1onetime~1access/post/requestBody/content/application~1json/schema/allOf/1/properties/accounts/items'
                    description: List of identifiers that will auto select the appropriate accounts.
                  account_types:
                    type: array
                    default: []
                    items:
                      $ref: '#/paths/~1onetime~1account-verification/post/requestBody/content/application~1json/schema/allOf/1/properties/account_types/items'
                    description: This will auto select a connection strategy based on the available account types. It is not guaranteed to retrieved all types, but best effort is taken based on order (first is highest priority).
                  allow_multi_selection:
                    type: boolean
                    default: true
                    description: Indicates whether to allow multiple accounts to be selected. Ignored if `accounts` is set.
                  reporting_period:
                    type: integer
                    default: 12
                    minimum: 4
                    description: Number of months to the past for which to generate the report.
      responses:
        '201':
          $ref: '#/paths/~1ongoing~1sync/post/responses/201'
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
  /rest/income-report:
    get:
      summary: Get and Generate Income Report
      operationId: getAndGenerateIncomeReport
      description: Get Income Report for an account or an access creating the report on the fly
      parameters:
      - $ref: '#/paths/~1catalog/get/parameters/0'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/5'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/4'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/0'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/1'
      tags:
      - Income Report
      security:
      - user_auth: []
      responses:
        '200':
          description: The income report generated as per request parameters
          content:
            application/json:
              schema:
                type: object
                description: The user's income report
                properties:
                  id:
                    type: string
                    format: uuid
                    description: ID of the report
                    example: fc1dacd6-25c8-e7e2-f106-aaf2ea8b09f
                  period:
                    type: integer
                    description: The period in months for which the income report was requested
                  income:
                    description: The income streams and their summaries
                    allOf:
                    - $ref: '#/paths/~1rest~1income-report/get/responses/200/content/application~1json/schema/properties/regular_expenses/items'
                    - type: object
                      properties:
                        primary:
                          description: A primary income stream
                          $ref: '#/paths/~1rest~1risk-reports/post/responses/200/content/application~1json/schema/properties/income/properties/primary/allOf/1'
                  regular_expenses:
                    type: array
                    description: Regular expenses, such as rent payments, monthly phone payments, quarterly radio tax payments
                    items:
                      type: object
                      properties:
                        summary:
                          description: A summary of an income/expense stream, such as low, high, average values
                          $ref: '#/paths/~1rest~1risk-reports/post/responses/200/content/application~1json/schema/properties/expenses/properties/summary'
                        streams:
                          type: array
                          description: List of income/expense streams
                          items:
                            $ref: '#/paths/~1rest~1risk-reports/post/responses/200/content/application~1json/schema/properties/income/properties/regular/properties/streams/items'
                      required:
                      - summary
                      - streams
                  variable_expenses:
                    type: array
                    description: Variable expenses - all expenses that are not regular, such as grocery shopping, buying clothes
                    items:
                      $ref: '#/paths/~1rest~1income-report/get/responses/200/content/application~1json/schema/properties/regular_expenses/items'
                  disposable_income:
                    description: 'The amount left after deducting regular expenses from the total income.

                      The formula for calculating this would be total_income - regular_expenses'
                    allOf:
                    - type: object
                      properties:
                        total:
                          type: number
                          format: float
                          example: 1234.56
                          description: Total amount of transactions
                        low:
                          type: number
                          format: float
                          example: -220.2
                          description: Highest expense / Lowest deposit
                        high:
                          type: number
                          format: float
                          example: 1400.5
                          description: Lowest expense / Highest deposit
                        average:
                          type: number
                          description: The arithmetic average of the amounts
                          format: float
                          example: 2123.25
                      required:
                      - total
                      - low
                      - high
                      - average
                    - type: object
                      properties:
                        ratio:
                          type: number
                          format: float
                          description: 'The ratio of the disposable/discretionary income to the total income amount.

                            Example: a total income amount of 1000 with a leftover of 500 yields a ratio of 0.5'
                          example: 0.32
                      required:
                      - ratio
                  discretionary_income:
                    $ref: '#/paths/~1rest~1income-report/get/responses/200/content/application~1json/schema/properties/disposable_income'
                    description: 'The amount left after deducting variable expense from the disposable income.

                      It could be expressed as: total_income - (regular_expenses + variable_expenses)'
                  created_at:
                    type: string
                    format: date-time
                    description: The time at which the report was generated.
                required:
                - id
                - period
                - income
                - regular_expenses
                - variable_expenses
                - disposable_income
                - discretionary_income
                - created_at
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
  /rest/income-reports:
    post:
      summary: Create income report
      operationId: createIncomeReport
      description: Create income report directly via API (without using the widget). This endpoint is only relevant for licensed partners with a direct API integration.
      tags:
      - Income Report
      security:
      - user_auth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account_ids:
                  type: array
                  description: Restrict the risk report to given accounts (do not consider other accounts for the report)
                  items:
                    $ref: '#/paths/~1rest~1accounts~1{account-id}/get/parameters/0/schema'
                reporting_period:
                  type: integer
                  default: 12
                  minimum: 4
                  description: Number of months to the past for which to generate the risk report.
      responses:
        '200':
          $ref: '#/paths/~1rest~1income-report/get/responses/200'
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
  /rest/income-reports/{id}:
    get:
      summary: Get income report
      operationId: getIncomeReport
      description: Get the income report which was created earlier. The language of the categories can be customized by using the `Accept-Language` HTTP header.
      tags:
      - Income Report
      security:
      - user_auth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: ID of the report
        example: fc1dacd6-25c8-e7e2-f106-aaf2ea8b09f
      responses:
        '200':
          $ref: '#/paths/~1rest~1income-report/get/responses/200'
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
components:
  securitySchemes:
    user_auth:
      type: http
      description: 'In order to access any information belonging to a user, a client has to authenticate with a token linking itself to the user.  This token is called an `access token` and contains information on the client, the user and the level of access the client has to the users data. In order to authenticate using such an access token the HTTP header `Authorization` is set to `Bearer <access token>`. The  `access token` is formatted

        as a JSON Web Token according to [RFC7519](https://tools.ietf.org/html/rfc7519)


        Such an `access token` is either returned when


        * exchanging an authorization code after a successful OAuth login flow

        * logging in with the user''s credentials

        * exchanging a refresh token, which is returned at either of the aforementioned points


        **Authentication errors**


        In case of an authentication error a HTTP code 401 response is returned containing further

        details on the kind of error in the `WWW-Authenticate` header.


        In addition to the below listed scope the flags are used for simple boolean permissions.


        | Flag            | Description                                  |

        | --              | --                                           |

        | submit_payments | Allow submission of payments to bank server  |

        | offline         | Access finX API when the user is not present |

        | create_user     | Allow creation of finX accounts              |


        **Example**


        The string `"accounts=rw submit_payments"` is URL-encoded and passed as the URL

        parameter `scope`.'
      scheme: bearer
      bearerFormat: JWT
      x-bearerInfoFunc: app.decode_token
      x-scopes:
        accounts=rw: Modify accounts
        accounts=ro: Read accounts
        balance=ro: Read account balance
        securities=ro: Read securities
        transactions=ro: Read transactions
        transactions=rw: Modify transactions
        payments=ro: Read payments
        payments=rw: Create/modify payments
        submit_payments: Submit payment to service provider
        user=ro: Read user information
        user=rw: Modify user information
    client_auth:
      x-basicInfoFunc: app.basic_auth
      type: http
      scheme: basic
      description: Client authentication is performed via [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication) with client ID as username and client secret as password.
x-provenance:
  method: searched
  source: https://docs.qwist.com/reference
  harvested: '2026-10-21'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.qwist.com/reference/addprovideraccess.md
  - https://docs.qwist.com/reference/categorizetransactions.md
  - https://docs.qwist.com/reference/createaccesstoken.md
  - https://docs.qwist.com/reference/createaccountverification.md
  - https://docs.qwist.com/reference/createcontract.md
  - https://docs.qwist.com/reference/createincomereport.md
  - https://docs.qwist.com/reference/createmanualsync.md
  - https://docs.qwist.com/reference/createnotification.md
  - https://docs.qwist.com/reference/createonetimeaccess.md
  - https://docs.qwist.com/reference/createonetimeincomereport.md
  - https://docs.qwist.com/reference/createonetimepayment.md
  - https://docs.qwist.com/reference/createonetimeriskreport.md
  - https://docs.qwist.com/reference/createongoingaccess.md
  - https://docs.qwist.com/reference/createongoingpayment.md
  - https://docs.qwist.com/reference/createongoingriskreport.md
  - https://docs.qwist.com/reference/createpayment.md
  - https://docs.qwist.com/reference/createpaymentfromaccount.md
  - https://docs.qwist.com/reference/createqwistlink.md
  - https://docs.qwist.com/reference/createriskreport.md
  - https://docs.qwist.com/reference/createsync.md
  - https://docs.qwist.com/reference/createupload.md
  - https://docs.qwist.com/reference/createuser.md
  - https://docs.qwist.com/reference/createverifyandpay.md
  - https://docs.qwist.com/reference/deleteaccount.md
  - https://docs.qwist.com/reference/deleteclientuser.md
  - https://docs.qwist.com/reference/deletecontract.md
  - https://docs.qwist.com/reference/deletenotification.md
  - https://docs.qwist.com/reference/deletepayment.md
  - https://docs.qwist.com/reference/deleteprovideraccess.md
  - https://docs.qwist.com/reference/deleteuser.md
  - https://docs.qwist.com/reference/getaccount.md
  - https://docs.qwist.com/reference/getaccountbalance.md
  - https://docs.qwist.com/reference/getaccountverificationreceipt.md
  - https://docs.qwist.com/reference/getandgenerateincomereport.md
  - https://docs.qwist.com/reference/getartifact.md
  - https://docs.qwist.com/reference/getcategories.md
  - https://docs.qwist.com/reference/getcategoriesforaccess.md
  - https://docs.qwist.com/reference/getcategoriesforaccount.md
  - https://docs.qwist.com/reference/getcategorytree.md
  - https://docs.qwist.com/reference/getcontract.md
  - https://docs.qwist.com/reference/getcredential.md
  - https://docs.qwist.com/reference/getincomereport.md
  - https://docs.qwist.com/reference/getinsurance.md
  - https://docs.qwist.com/reference/getloan.md
  - https://docs.qwist.com/reference/getnotification.md
  - https://docs.qwist.com/reference/getpaymentchallenge.md
  - https://docs.qwist.com/reference/getpaymentchallengeofaccount.md
  - https://docs.qwist.com/reference/getpaymentinitstatus.md
  - https://docs.qwist.com/reference/getpaymentinitstatusofaccount.md
  - https://docs.qwist.com/reference/getpaymentofaccount.md
  - https://docs.qwist.com/reference/getpaymentpartners.md
  - https://docs.qwist.com/reference/getpaymentpartnersforaccess.md
  - https://docs.qwist.com/reference/getpaymentpartnersforaccount.md
  - https://docs.qwist.com/reference/getpaymentreceipt.md
  - https://docs.qwist.com/reference/getprovideraccess.md
  - https://docs.qwist.com/reference/getriskreport.md
  - https://docs.qwist.com/reference/getsecurityofaccount.md
  - https://docs.qwist.com/reference/getsyncchallenge.md
  - https://docs.qwist.com/reference/getsyncstatus.md
  - https://docs.qwist.com/reference/gettimeline.md
  - https://docs.qwist.com/reference/gettimelineforaccess.md
  - https://docs.qwist.com/reference/gettimelineforaccount.md
  - https://docs.qwist.com/reference/gettransaction.md
  - https://docs.qwist.com/reference/gettransactionofaccount.md
  - https://docs.qwist.com/reference/getuploadstatus.md
  - https://docs.qwist.com/reference/getuser.md
  - https://docs.qwist.com/reference/getversion.md
  - https://docs.qwist.com/reference/initpayment.md
  - https://docs.qwist.com/reference/initpaymentofaccount.md
  - https://docs.qwist.com/reference/listaccounts.md
  - https://docs.qwist.com/reference/listaccountsofaccess.md
  - https://docs.qwist.com/reference/listbanks.md
  - https://docs.qwist.com/reference/listcatalog.md
  - https://docs.qwist.com/reference/listcatalogclientauth.md
  - https://docs.qwist.com/reference/listclientusers.md
  - https://docs.qwist.com/reference/listcontracts.md
  - https://docs.qwist.com/reference/listcontractsofaccess.md
  - https://docs.qwist.com/reference/listcontractsofaccount.md
  - https://docs.qwist.com/reference/listcredentials.md
  - https://docs.qwist.com/reference/listinsurances.md
  - https://docs.qwist.com/reference/listinsurancesofaccess.md
  - https://docs.qwist.com/reference/listloans.md
  - https://docs.qwist.com/reference/listloansofaccess.md
  - https://docs.qwist.com/reference/listnotifications.md
  - https://docs.qwist.com/reference/listpaymentchallenges.md
  - https://docs.qwist.com/reference/listpaymentchallengesofaccount.md
  - https://docs.qwist.com/reference/listpayments.md
  - https://docs.qwist.com/reference/listpaymentsofaccount.md
  - https://docs.qwist.com/reference/listprovideraccesses.md
  - https://docs.qwist.com/reference/listsecurities.md
  - https://docs.qwist.com/reference/listsecuritiesofaccount.md
  - https://docs.qwist.com/reference/listservices.md
  - https://docs.qwist.com/reference/listsyncchallenges.md
  - https://docs.qwist.com/reference/listtransactions.md
  - https://docs.qwist.com/reference/listtransactionsofaccount.md
  - https://docs.qwist.com/reference/patchcredential.md
  - https://docs.qwist.com/reference/removepinfromprovideraccess.md
  - https://docs.qwist.com/reference/replacenotifications.md
  - https://docs.qwist.com/reference/revokeoauthtoken.md
  - https://docs.qwist.com/reference/solvepaymentchallenge.md
  - https://docs.qwist.com/reference/solvepaymentchallengeofaccount.md
  - https://docs.qwist.com/reference/solvesyncchallenge.md
  - https://docs.qwist.com/reference/updatecontract.md
  - https://docs.qwist.com/reference/updatenotification.md
  - https://docs.qwist.com/reference/updateuser.md
  merge:
    pages: 105
    deduped: 1107
    conflicts_kept_first: 0