Qwist Synchronizations API

openapi: 3.2.0
info:
  title: nrich Synchronizations 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: Synchronizations
paths:
  /rest/accesses/{access-id}/syncs:
    post:
      summary: Start provider synchronization
      operationId: createSync
      description: 'In order for the finX API to have up-to-date transaction and account information, it needs to query the bank servers, a process which is called synchronization. With this call you can create a new synchronization to fetch updated data from the provider.

        If the confidential parts of the provider credentials have not been given when creating the access they have to be send with this request. If the `save_secrets` flag is set to `true` the credentials are stored in the finX backend, so that subsequent synchronizations can be triggered without providing the credentials again.'
      tags:
      - Synchronizations
      parameters:
      - $ref: '#/paths/~1rest~1accesses~1{access-id}/get/parameters/0'
      security:
      - user_auth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                credentials:
                  $ref: '#/paths/~1rest~1accesses/post/requestBody/content/application~1json/schema/properties/credentials'
                save_secrets:
                  type: boolean
                  description: Indicates whether the confidential parts of the credentials should be saved for future access synchronization operations. If set to `false` previously saved secrets are discarded at the end of the synchronization.
                disable_notifications:
                  type: boolean
                  example: true
                  default: false
                  description: Indicates whether the [configured notification](/#tag/Notifications) events are triggered at the end of the synchronization process.
                redirect_uri:
                  type: string
                  format: url
                  example: https://nrich.example.com/callback
                  description: The URI to which the user is redirected at the end of a redirect based authentication flow. The `state` that has been specified in the request will be attached as a query parameter to the URI.
                state:
                  $ref: '#/paths/~1rest~1notifications~1{notification-id}/put/requestBody/content/application~1json/schema/properties/state'
                scope:
                  allOf:
                  - type: array
                    description: 'Defines the scope of the synchronization.

                      * `"ACCOUNTS"`: Only fetch basic account data (e.g. holder name, IBAN etc.). Add new provider accounts to previously synced accesses.

                      * `"TRANSACTIONS"`: Fetch transaction and account data.'
                    items:
                      type: string
                      enum:
                      - ACCOUNTS
                      - TRANSACTIONS
                  default:
                  - TRANSACTIONS
                reuse_auth_method:
                  type: boolean
                  example: false
                  default: true
                  description: 'Indicates whether the last selected authentication **method** should be re-used for this synchronization. This minimizes the amount of challenges that have to be solved in the course of the synchronization operation.

                    '
                reuse_auth_medium:
                  type: boolean
                  example: false
                  default: true
                  description: 'Indicates whether the last selected authentication **medium** should be re-used for this synchronization. This minimizes the amount of challenges that have to be solved in the course of the synchronization operation.

                    '
                psu_ip:
                  type: string
                  format: IP
                  description: 'The IP address of the end-user for whom the synchronization is triggered. This might be required by the provider. It is advised to provide this value whenever possible.

                    '
                period:
                  type: integer
                  description: Defines the number of days of transaction history that is requested from the financial provider.
      responses:
        '201':
          description: Synchronization status.
          content:
            application/json:
              schema:
                type: object
                description: A handle to refer to a synchronization operation with a financial provider. In the course of the execution of the synchronization updated data (e.g. transaction statement, balance) will be fetched from the provider.
                properties:
                  id:
                    $ref: '#/paths/~1rest~1transactions/get/parameters/11/schema'
                  status:
                    $ref: '#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/status'
                  state:
                    type: string
                    description: The `state` that was being provided in the request when creating the synchronization.
                  challenge:
                    $ref: '#/paths/~1rest~1accesses~1{access-id}~1syncs~1{sync-id}~1challenges~1{challenge-id}/get/responses/200/content/application~1json/schema'
                  error:
                    type: object
                    description: Error detailing why the background operation failed.
                    properties:
                      code:
                        $ref: '#/paths/~1catalog/get/responses/401/content/application~1json/schema/properties/error/properties/code'
                      name:
                        type: string
                        description: Error summary.
                      message:
                        type: string
                        description: Error message as provided by the financial provider.
                      description:
                        type: string
                        description: Human readable description of the error.
                      group:
                        $ref: '#/paths/~1catalog/get/responses/401/content/application~1json/schema/properties/error/properties/group'
                  created_at:
                    $ref: '#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at'
                    description: Time at which the sync was created.
                    example: '2019-08-31T12:13:09.000Z'
                  started_at:
                    $ref: '#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at'
                    description: Time at which the sync was started. Will be omitted as long as the sync is still in the `QUEUED` state.
                    example: '2019-08-31T12:13:11.000Z'
                  ended_at:
                    $ref: '#/paths/~1uploads/post/responses/200/content/application~1json/schema/properties/ended_at'
                    description: Time at which the sync was ended. Will be omitted as log as the sync is not in the `COMPLETED` state.
                    example: '2019-08-31T12:13:45.000Z'
                  redirect_uri:
                    type: string
                    format: url
                    description: The URL where users will be redirected after completing their interaction with the Widget.
                required:
                - id
                - created_at
                - status
        '400':
          $ref: '#/paths/~1rest~1user/put/responses/400'
        '401':
          $ref: '#/paths/~1catalog/get/responses/401'
  /rest/accesses/{access-id}/syncs/{sync-id}:
    get:
      summary: Get synchronization status
      operationId: getSyncStatus
      tags:
      - Synchronizations
      parameters:
      - $ref: '#/paths/~1rest~1accesses~1{access-id}/get/parameters/0'
      - in: path
        name: sync-id
        required: true
        schema:
          $ref: '#/paths/~1rest~1transactions/get/parameters/11/schema'
      security:
      - user_auth: []
      responses:
        '200':
          $ref: '#/paths/~1rest~1accesses~1{access-id}~1syncs/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'
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