Skip to content
Developer home

Multi-account linking

  Less than to read

Many users of Banking Service will only have a handful of bank accounts they want to integrate with their software. However, we know there are users with upwards of 100 accounts per financial institution and the existing (single account) flow means onboarding each of these 1 by 1 is time-consuming.

This walkthrough covers how we can use the multi-account linking flow to link additional accounts to an existing BankConnection. This means you don’t beed to repeat the single account flow multiple times. This guide walks through the API calls made to and from the Banking Service from your application and the consuming product. It demonstrates the multi-account linking flow detailed within our Postman collection.

Read our API flow overview before following this walkthrough. This covers any prerequisites and how to use our Postman collections.

API flow diagram

Flow diagram displaying the authorisation flow

1. Initiate multi-account linking

Depending on the user’s product, they may support the ability to link all accounts under a single authorisation, this is called multi-account linking.

The user can initate this multi-account link flow from within the consuming Sage product. This informs the Banking Service to get all available accounts under the same authorisation as the account created during the single account flow. Banking Service then sends a request the provider’s GET /availableaccounts endpoint through the connector API.


Note: Before a user can benefit from the multi-account flow, they must first onboard at least 1 account for the same financial institution via the single account flow. This is required as they still need to authenticate with the institution and grant any necessary consents.

GET /availableaccounts

Connector API

When the banking service calls this endpoint they will pass a single externalId in the query parameters:

GET /availableaccounts?externalId=X

This externalId is the identifier you give when first providing us with accounts through the patch authorisations call on the onboarding flow. The provider should use this externalId to return an array of available accounts under the same authorisation. These are then returned to the consuming product for the user to select.

Example of response:

        "accountType": "string",
        "accountName": "string",
        "externalId": "string",
        "bankIdentifier": "e9316993-a44f-49a7-b891-2374c77ce5a4",
        "accountIdentifier": "4de7d7a7-b222-4024-96b5-95b20d350b77",
        "branchIdentifier": "string"
        "accountType": "string",
        "accountName": "string",
        "externalId": "string",
        "bankIdentifier": "a4676993-a44f-49a7-b891-2374c77ce5a4",
        "accountIdentifier": "7vh6d3a2-b222-4024-96b5-95b20d350b77",
        "branchIdentifier": "string"

Description of the fields:

  • accountType: (string) is the type of account; ‘business’, ‘savings’, ‘loan’, ‘creditCard’, ‘corporate’ or ‘personal’.
  • accountName: (string) The bank account name that is to be displayed to the customer. Can use account name + masked account number to help customers identify.
  • externalId: (string) The provider’s own unique identifier for the bank account.
  • bankIdentifier: (string) The real-world bank identifier for the specific bank. Banking service recommends this to be an identifier that represents the customers credentials.
  • accountIdentifier: (string) The real-world account number for the bank account. Usually this isn’t the account number but a unique identifier held by the provider.
  • branchIdentifier: (string) The real-world branch identifier for the bank account. If you do not wish to use please populate with the string ‘n/a’.

The user can use in-product functionality to map their bank accounts to the available accounts returned by the provider. For each mapped account:

  • A bank account is created in Banking Service.
  • The details of this bank account are passed to the user’s product to be stored.
  • Banking Service sends a ‘resource created’ notification to the provider.

POST /notification

Connector API

For each linked bank account, Banking Service sends a resource created notification to the provider. This is done through a POST request to the provider’s /notification endpoint with the following payload:

  "type": "resourceCreated",
  "resource": {
    "id": "36aed119-675f-4507-9da3-06a5914d95ee",
    "type": "bankAccount",
    "url": ""
  "additionalData": {
    "externalId": "13b437a2-e0bb-4d06-8dc1-618ea2b6a723:0b035aef-9e1e-406e-9815-06409757f05e",
    "requestedStartDate": "2021-06-29T11:05:29Z",
    "bankId": "10aaeee6-4691-4443-8198-df39aaa8007c"

Description of the fields:

  • resource.type – For linking an account with the multi-account linking flow, the type will be bankAccountFromCandidate.
  • – The identifier of the newly created bankAccount resource.
  • additionalData.externalId – The externalId that was provided to Banking Service by the provider in the /authorisations PATCH call.
  • requestedStartDate – The start date which the user has requested to start recieving transactions from.


This walkthrough has covered the Banking Service flow for linking multiple accounts to a single authorisation.

We have shown how you initiate this flow from the consuming product, which trigger Banking Service to call the provider’s GET /availableaccounts endpoint to retrieve a list of accounts.

We have also covered how the provider is notified through the POST /notifications endpoint when a new account has been linked.

Next steps

Discover how to push transactions into Banking Service.