Qwist Contracts API

openapi: 3.2.0
info:
  title: nrich Contracts 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: Contracts
paths:
  /rest/accesses/{access-id}/contracts:
    get:
      summary: List contracts of access
      operationId: listContractsOfAccess
      description: Retrieve a list of contracts associated with this access.
      tags:
      - Contracts
      parameters:
      - $ref: '#/paths/~1catalog/get/parameters/0'
      - $ref: '#/paths/~1rest~1accesses~1{access-id}/get/parameters/0'
      - $ref: '#/paths/~1auth~1users/get/parameters/1'
      - $ref: '#/paths/~1auth~1users/get/parameters/0'
      security:
      - user_auth: []
      responses:
        '200':
          $ref: '#/paths/~1rest~1contracts/get/responses/200'
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
        4XX:
          $ref: '#/paths/~1rest~1loans/get/responses/4XX'
  /rest/accounts/{account-id}/contracts:
    get:
      summary: List contracts of account
      operationId: listContractsOfAccount
      description: Retrieve a list of contracts associated with this account.
      tags:
      - Contracts
      parameters:
      - $ref: '#/paths/~1catalog/get/parameters/0'
      - $ref: '#/paths/~1rest~1accounts~1{account-id}/get/parameters/0'
      - $ref: '#/paths/~1auth~1users/get/parameters/1'
      - $ref: '#/paths/~1auth~1users/get/parameters/0'
      security:
      - user_auth: []
      responses:
        '200':
          $ref: '#/paths/~1rest~1contracts/get/responses/200'
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
        4XX:
          $ref: '#/paths/~1rest~1loans/get/responses/4XX'
  /rest/contracts:
    get:
      summary: List contracts
      operationId: listContracts
      description: Retrieve a list of contracts associated with this user.
      tags:
      - Contracts
      parameters:
      - $ref: '#/paths/~1catalog/get/parameters/0'
      - $ref: '#/paths/~1auth~1users/get/parameters/1'
      - $ref: '#/paths/~1auth~1users/get/parameters/0'
      security:
      - user_auth: []
      responses:
        '200':
          description: List of contracts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/paths/~1rest~1contracts/post/responses/201/content/application~1json/schema'
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
        4XX:
          $ref: '#/paths/~1rest~1loans/get/responses/4XX'
    post:
      summary: Create contract
      operationId: createContract
      description: Create a new contract based on a given set of transactions.
      tags:
      - Contracts
      security:
      - user_auth: []
      parameters:
      - $ref: '#/paths/~1auth~1user/post/parameters/0'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                payment_frequency:
                  $ref: '#/paths/~1rest~1contracts~1{contract-id}/put/requestBody/content/application~1json/schema/properties/payment_frequency'
                transaction_ids:
                  type: array
                  description: "The transactions which should be part of the new contract.\n\n**Limitations:**\n  * Currently **only one** transaction can be provided.\n  * The transactions must not already be associated with another contract."
                  items:
                    $ref: '#/paths/~1rest~1transactions~1{transaction-id}/get/parameters/1/schema'
                  minItems: 1
                  maxItems: 1
              required:
              - payment_frequency
              - transaction_ids
      responses:
        '201':
          description: Contract details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    $ref: '#/paths/~1rest~1contracts~1{contract-id}/get/parameters/1/schema'
                  account_id:
                    $ref: '#/paths/~1rest~1accounts~1{account-id}/get/parameters/0/schema'
                  is_active:
                    type: boolean
                    description: Status of the contract. A contract is considered active if at least one corresponding payment has been observed in the last two payment periods.
                    example: true
                  payment_frequency:
                    $ref: '#/paths/~1rest~1contracts~1{contract-id}/put/requestBody/content/application~1json/schema/properties/payment_frequency'
                  payment_partner:
                    $ref: '#/paths/~1rest~1payment-partners/get/responses/200/content/application~1json/schema/items/allOf/0'
                  categories:
                    type: array
                    description: Categories attached to the contract.
                    items:
                      $ref: '#/paths/~1category-tree/get/responses/200/content/application~1json/schema/items'
                  is_recognized:
                    type: boolean
                    description: Indicates if the contract has been automatically derived from the transaction history. All [user provided contracts](/reference/createcontract) initially have a value of `false`.
                    example: true
                  transactions:
                    type: object
                    description: Transaction statistics for this contract.
                    properties:
                      href:
                        type: string
                        format: uri
                        description: A link to the list of transactions issued in the scope of this contract.
                      count:
                        type: integer
                        example: 40
                        description: Number of transactions of this contract.
                      total:
                        type: number
                        format: float
                        example: 1234.56
                        description: Total amount of transactions of this contract.
                      average:
                        type: number
                        format: float
                        description: Average amount transferred per payment.
                        example: 30.86
                      currency:
                        $ref: '#/paths/~1rest~1loans~1{loan-id}/get/responses/200/content/application~1json/schema/properties/currency'
                        description: Three-letter code of the currency used for the total and average amounts.
                    required:
                    - href
                    - count
                    - total
                    - average
                    - currency
                  last_paid_at:
                    $ref: '#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at'
                    description: Last recognized payment date for this contract.
                    example: '2018-08-26T10:15:00.000Z'
                  modified_at:
                    $ref: '#/paths/~1rest~1loans~1{loan-id}/get/responses/200/content/application~1json/schema/properties/modified_at'
                  created_at:
                    $ref: '#/paths/~1rest~1accesses/get/responses/200/content/application~1json/schema/items/properties/created_at'
                required:
                - id
                - account_id
                - categories
                - is_active
                - is_recognized
                - payment_frequency
                - payment_partner
                - transactions
                - last_paid_at
                - created_at
                - modified_at
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
        4XX:
          $ref: '#/paths/~1rest~1loans/get/responses/4XX'
  /rest/contracts/{contract-id}:
    get:
      summary: Get contract
      operationId: getContract
      description: Get contract by ID
      tags:
      - Contracts
      parameters:
      - $ref: '#/paths/~1catalog/get/parameters/0'
      - name: contract-id
        in: path
        required: true
        schema:
          type: string
          description: ID of the contract.
          example: C12345.6
      security:
      - user_auth: []
      responses:
        '200':
          $ref: '#/paths/~1rest~1contracts/post/responses/201'
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
        '404':
          $ref: '#/paths/~1auth~1token/post/responses/404'
        4XX:
          $ref: '#/paths/~1rest~1loans/get/responses/4XX'
    put:
      summary: Modify contract
      operationId: updateContract
      description: Update the properties of a contract. This is only possible as long as the contract properties are not automatically derived from the transaction history but are still managed by the user (`is_recognized` is `false`).
      tags:
      - Contracts
      parameters:
      - $ref: '#/paths/~1rest~1contracts~1{contract-id}/get/parameters/1'
      - $ref: '#/paths/~1auth~1user/post/parameters/0'
      security:
      - user_auth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                payment_frequency:
                  type: string
                  description: Frequency of payments for this contract.
                  enum:
                  - monthly
                  - quarterly
                  - half-yearly
                  - yearly
              required:
              - payment_frequency
      responses:
        '200':
          $ref: '#/paths/~1rest~1contracts/post/responses/201'
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
        '404':
          $ref: '#/paths/~1auth~1token/post/responses/404'
        4XX:
          $ref: '#/paths/~1rest~1loans/get/responses/4XX'
    delete:
      summary: Delete contract
      operationId: deleteContract
      description: Delete a contract.
      tags:
      - Contracts
      parameters:
      - $ref: '#/paths/~1rest~1contracts~1{contract-id}/get/parameters/1'
      security:
      - user_auth: []
      responses:
        '204':
          $ref: '#/paths/~1rest~1user/delete/responses/204'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
        '404':
          $ref: '#/paths/~1auth~1token/post/responses/404'
        4XX:
          $ref: '#/paths/~1rest~1loans/get/responses/4XX'
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