Qwist Aggregations API

openapi: 3.2.0
info:
  title: nrich Aggregations 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: Aggregations
paths:
  /rest/accesses/{access-id}/categories:
    get:
      summary: Get categories for access
      operationId: getCategoriesForAccess
      description: Retrieve a list of categories associated to the transactions of this access. Each category entry also includes aggregated statistics of the referenced transactions like total amount, number of transactions, high and low values.
      tags:
      - Aggregations
      parameters:
      - $ref: '#/paths/~1catalog/get/parameters/0'
      - $ref: '#/paths/~1rest~1accesses~1{access-id}/get/parameters/0'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/5'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/3'
      - $ref: '#/paths/~1rest~1categories/get/parameters/4'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/0'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/1'
      - $ref: '#/paths/~1rest~1categories/get/parameters/7'
      - $ref: '#/paths/~1rest~1categories/get/parameters/8'
      - $ref: '#/paths/~1rest~1categories/get/parameters/9'
      security:
      - user_auth: []
      responses:
        '200':
          $ref: '#/paths/~1rest~1categories/get/responses/200'
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
  /rest/accesses/{access-id}/payment-partners:
    get:
      summary: Get payment partners for access
      operationId: getPaymentPartnersForAccess
      description: Retrieve a list of payment partners associated to the transactions of this access. Each entry includes aggregated statistics of the referenced transactions like total amount, number of transactions and average payment amount.
      tags:
      - Aggregations
      parameters:
      - $ref: '#/paths/~1rest~1accesses~1{access-id}/get/parameters/0'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/5'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/3'
      - $ref: '#/paths/~1rest~1categories/get/parameters/4'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/0'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/1'
      - $ref: '#/paths/~1rest~1categories/get/parameters/7'
      - $ref: '#/paths/~1rest~1categories/get/parameters/8'
      - $ref: '#/paths/~1rest~1categories/get/parameters/9'
      security:
      - user_auth: []
      responses:
        '200':
          $ref: '#/paths/~1rest~1payment-partners/get/responses/200'
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
  /rest/accounts/{account-id}/categories:
    get:
      summary: Get categories for account
      operationId: getCategoriesForAccount
      description: Retrieve a list of categories associated to the transactions of this account. Each category entry also includes aggregated statistics of the referenced transactions like total amount, number of transactions, high and low values.
      tags:
      - Aggregations
      parameters:
      - $ref: '#/paths/~1catalog/get/parameters/0'
      - $ref: '#/paths/~1rest~1accounts~1{account-id}/get/parameters/0'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/3'
      - $ref: '#/paths/~1rest~1categories/get/parameters/4'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/0'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/1'
      - $ref: '#/paths/~1rest~1categories/get/parameters/7'
      - $ref: '#/paths/~1rest~1categories/get/parameters/8'
      - $ref: '#/paths/~1rest~1categories/get/parameters/9'
      security:
      - user_auth: []
      responses:
        '200':
          $ref: '#/paths/~1rest~1categories/get/responses/200'
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
  /rest/accounts/{account-id}/payment-partners:
    get:
      summary: Get payment partners for account
      operationId: getPaymentPartnersForAccount
      description: Retrieve a list of payment partners associated to the transactions of this account. Each entry includes aggregated statistics of the referenced transactions like total amount, number of transactions and average payment amount.
      tags:
      - Aggregations
      parameters:
      - $ref: '#/paths/~1rest~1accounts~1{account-id}/get/parameters/0'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/3'
      - $ref: '#/paths/~1rest~1categories/get/parameters/4'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/0'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/1'
      - $ref: '#/paths/~1rest~1categories/get/parameters/7'
      - $ref: '#/paths/~1rest~1categories/get/parameters/8'
      - $ref: '#/paths/~1rest~1categories/get/parameters/9'
      security:
      - user_auth: []
      responses:
        '200':
          $ref: '#/paths/~1rest~1payment-partners/get/responses/200'
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
  /rest/categories:
    get:
      summary: Get categories
      operationId: getCategories
      description: Retrieve a list of categories associated to the transactions of this user. Each category entry also includes aggregated statistics of the referenced transactions like total amount, number of transactions, high and low values.
      tags:
      - Aggregations
      parameters:
      - $ref: '#/paths/~1catalog/get/parameters/0'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/4'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/5'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/3'
      - in: query
        name: period
        schema:
          type: string
        description: "Only select transactions that were booked in the specified period. Available formats are:\n\n  * `YYYY` yearly (e.g. 2019)\n  * `YYYY-mm` monthly (e.g. 2019-12)\n  * `YYYY-Qq` quarterly (e.g. 2019-Q1): `Q` is the literal character \"Q\" and `q` refers to the annual quarter.\n  * `YYYY-Ww` weekly (e.g. 2019-W23): `W` is the literal character \"W\" and `w` refers to the ISO week number.\n  * `YYYY-mm-dd` (e.g. 2019-12-24)"
      - $ref: '#/paths/~1rest~1timeline/get/parameters/0'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/1'
      - in: query
        name: sort
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        description: Determines the sort order of aggregation buckets. Sorting is performed based on the transactions total amount.
      - in: query
        name: amount_gte
        schema:
          type: string
        description: Only select transactions with an amount **equal or greater** than this value.
      - in: query
        name: amount_lt
        schema:
          type: string
        description: Only select transactions with an amount **less** than this value.
      security:
      - user_auth: []
      responses:
        '200':
          description: Transaction aggregation.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      description: ID of the nrich standard category.
                      example: 123
                    name:
                      type: string
                      description: Category name. The language depends on `Accept-Language` HTTP header provided in the request. Default is German.
                      example: Online-Shopping
                    transactions:
                      type: object
                      description: Transaction statistics for this category in the requested period.
                      properties:
                        href:
                          type: string
                          format: uri
                          example: https://api.nrich.qwist.cloud/rest/transactions?categories=3,14&since=2020-01-01&until=2020-01-31
                          description: A link to the list of the transactions matching this category.
                        count:
                          type: integer
                          example: 14
                          description: Number of transactions in this category.
                        total:
                          type: number
                          format: float
                          example: 1234.56
                          description: Total amount of transactions in this category.
                        low:
                          type: number
                          format: float
                          example: -220.2
                          description: Highest expense for this category.
                        high:
                          type: number
                          format: float
                          example: 1400.5
                          description: Highest deposit for this category.
                      required:
                      - href
                      - count
                      - total
                      - low
                      - high
                    children:
                      description: List of child categories of this category
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            $ref: '#/paths/~1rest~1categories/get/responses/200/content/application~1json/schema/items/properties/id'
                          name:
                            $ref: '#/paths/~1rest~1categories/get/responses/200/content/application~1json/schema/items/properties/name'
                          transactions:
                            $ref: '#/paths/~1rest~1categories/get/responses/200/content/application~1json/schema/items/properties/transactions'
                  required:
                  - id
                  - name
                  - transactions
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
  /rest/payment-partners:
    get:
      summary: Get payment partners
      operationId: getPaymentPartners
      description: Retrieve a list of payment partners associated to the transactions of this user. Each entry includes aggregated statistics of the referenced transactions like total amount, number of transactions and average payment amount.
      tags:
      - Aggregations
      parameters:
      - $ref: '#/paths/~1rest~1timeline/get/parameters/4'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/5'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/3'
      - $ref: '#/paths/~1rest~1categories/get/parameters/4'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/0'
      - $ref: '#/paths/~1rest~1timeline/get/parameters/1'
      - $ref: '#/paths/~1rest~1categories/get/parameters/7'
      - $ref: '#/paths/~1rest~1categories/get/parameters/8'
      - $ref: '#/paths/~1rest~1categories/get/parameters/9'
      security:
      - user_auth: []
      responses:
        '200':
          description: Transaction aggregation.
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                  - type: object
                    properties:
                      id:
                        type: string
                        format: UUID
                        example: 6702b891-b8e6-4892-8615-5440e39d3d0e
                        description: Payment partner ID.
                      name:
                        type: string
                        description: Name of payment partner.
                        example: Qwist GmbH
                      website_url:
                        type: string
                        format: url
                        description: The HTTP URL of the partners website
                        example: https://qwist.com
                      logo_url:
                        type: string
                        format: url
                        description: The HTTP URL of the partners logo
                        example: https://qwist.com/wp-content/uploads/2024/04/qwist_logo.svg
                      latitude:
                        type: number
                        format: float
                        description: Latitude of the partners physical location. If the partner is an online retailer i.e. Amazon - then the field is not provided
                        example: 52.508099
                      longitude:
                        type: number
                        format: float
                        description: Longitude of the partners physical location. If the partner is an online retailer i.e. Amazon - then the field is not provided
                        example: 13.329611
                    required:
                    - id
                    - name
                  - type: object
                    properties:
                      transactions:
                        type: object
                        description: Transaction statistics for this payment partner in the requested period.
                        properties:
                          href:
                            type: string
                            format: uri
                            example: https://api.nrich.qwist.cloud/rest/transactions?payment_partners=6702b891-b8e6-4892-8615-5440e39d3d0e&since=2020-01-01&until=2020-01-31
                            description: A link to a list of the transactions matching this payment partner.
                          count:
                            type: integer
                            example: 14
                            description: Number of transactions transferred to this payment partner.
                          total:
                            type: number
                            format: float
                            example: 279.86
                            description: Total amount of transactions for this payment partner.
                          average:
                            type: number
                            format: float
                            example: 19.99
                            description: Average amount paid to this payment partner.
                          last_booked_at:
                            $ref: '#/paths/~1auth~1users/get/parameters/2/schema'
                            description: Last booking date for this payment partner.
                            example: '2020-01-30'
                        required:
                        - href
                        - count
                        - total
                        - average
                        - last_booked_at
        '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