Multi-account link
Less than to read
Multi-account linking is a capability which allows users to quickly onboard a large number of accounts, easily. Multi-account linking means a customer can connect all of their accounts using the same authorisation with the bank or 3rd party provider. If the customer needs to reauthorize their connection, they only need to do this 1 time. All the accounts under the multi-account link will be reauthorized.
Prerequisites
Follow the standard onboarding proccess for the first account. Users can then utilise multi-account link to add any additional accounts under the same authorisation. The first account must have an active status before attempting to link additional accounts.
API flow diagram
Step 1. Obtain an access token
Before integrating with the Banking Service UI, integrate with the Authentication Service.
To work with Banking Service, you need an access token (JWT) from Authentication Service. The JWT is generated using the unique IDs of the organisation (organisationId) and company (companyId). This JWT can be provided as a bearer token for Banking Service requests through the authorisation header: ‘Bearer ‘.
2. Get candidate accounts
Candidates are accounts the user’s company has authorisation but have not yet linked to create an offical bank account connection. To get a list of candidate accounts call the GET /availablebankaccounts endpoint with a comma-separated list of bank account IDs. Banking Service will return any bank account candidates belonging to the same institution whose credentials match those of the provided bank accounts.
GET /{companyId}/availablebankaccounts
| Headers | Description |
|---|---|
x-application |
This is your application identifier which is generated from the Authentication Service. |
x-signature |
HMAC-SHA1 signature used to verify the consuming application. This is not required if using an authentication token such as JWT. A signing key unique to each consuming application will be provided for use in signing the initial onboarding of a new customer (POST /organisations). This will result in the return of a signing key unique to the new customer, to be used for all further API calls on their behalf. The signature should be generated by following these steps, and replacing all uses of the ‘token’ with the string ‘null’ |
Authorization |
This is the bearer token returned from your request to the /accesstoken endpoint as described in step 1. |
Content-Type |
This should be set as application/json. |
| Query Params | Description |
|---|---|
bankAccountIds |
A comma-separated list of UUIDs for bankAccounts. Up to 100 bankAccountIDs may be provided with each request. These should all be for the same country and institutions. |
filterConnected |
Boolean which if set to true will filter out already-connected candidate accounts from the result. |
Response
{
"refreshing": false,
"availableAccounts": [
{
"bankAccountCandidateId": "b84a7cb2-4802-45e4-bac7-891e844bac7b",
"bankIdentifier": "L77adrZwp5hq3dReaJarTeoajmnqoNhPWMaLK",
"accountIdentifier": "4QQbEz8dnoHQBLJaeVewSXPRmzP5KMCd767nA",
"accountKey": "public-sandbox-700ba836-2ffe-4dbb-1234-e7fdd7554cfc",
"accountType": "depository",
"defaultCurrency": "GBP",
"accountName": "Plaid Money Market",
"dataProvider": "indirect",
"aggregatorId": "ins_117181",
"aggregatorName": "plaid",
"authAlwaysRequired": false,
"metadata": {
"maskedAccountNumber": 4444,
"accountName": "Plaid Money Market",
"alternativeAccountName": "Plaid Platinum Standard 1.85% Interest Money Market",
"accountType": "depository",
"accountSubType": "money market",
"availableBalance": 43200,
"currentBalance": 43200,
"connected": false,
"connectedBankAccountId": "null",
"refreshing": false
},
"lastTransaction": {
"amount": 200,
"date": "2020-06-17T00:00:00.000Z"
}
}
]
}
3. Link available account
The user should then have the option to link any of the returned accounts to a given in-product bank account. To convert the account from a candidate to a real bank account, pass the bankAccountCandidateId and the transactions requestedStartDate through the POST /linkavailablebankaccount endpoint.
bankAccountCandidateId: (UUID) the ID of a candidate returned in the previous step. This can change over time as the candidates may be refreshed by other actions. The linking request should take place soon after the retrieval of bank account candidates from the Banking Service API.requestedStartDate: (ISO datetime, optional) the requested start date the user wants to retrieve transactions from.
Banking Service will complete the connection and return a bank account object with a valid bankAccountId which should be stored. Only 1 candidate may be linked for each request but multiple calls may be made by the client if the user has selected multiple accounts.
POST /{companyId}/linkavailablebankaccount
| Headers | Description |
|---|---|
x-application |
This is your application identifier which is generated from the Authentication Service. |
x-signature |
HMAC-SHA1 signature used to verify the consuming application. This is not required if using an authentication token such as JWT. A signing key unique to each consuming application will be provided for use in signing the initial onboarding of a new customer (POST /organisations). This will result in the return of a signing key unique to the new customer, to be used for all further API calls on their behalf. The signature should be generated by following these steps, and replacing all uses of the ‘token’ with the string ‘null’ |
Authorization |
This is the bearer token returned from your request to the /accesstoken endpoint as described in step 1. |
Content-Type |
This should be set as application/json. |
| Query Params | Description |
|---|---|
bankAccountIds |
A comma-separated list of UUIDs for bankAccounts. |
firstConnected |
Boolean which if set to true will filter out already-connected candidate accounts from the result. |
Request Body
{
"bankAccountCandidateId": "b84a7cb2-4802-45e4-bac7-891e844bac7b",
"requestedStartDate": "2016-06-17T00:00:00.000Z"
}
Response
{
"bankId": "b84a7cb2-4802-45e4-bac7-891e844bac7b",
"users": [
{
"userId": "6a81e718-e4dd-467d-a318-3abea13ad244",
"accessLevel": "admin"
}
],
"bankIdentifier": "11111111",
"accountIdentifier": "0123456789",
"accountType": "Checking",
"accountTypes": {
"isCreditCard": false
},
"branchIdentifier": "branch_id",
"accountKey": "account_key",
"defaultCurrency": "USD",
"accountName": "Mr J Bloggs",
"clientAuthorisationToken": "A45FDE390A1FF209",
"status": "active",
"createdDate": "2016-07-15T17:53:35.000Z",
"modifiedDate": "2016-07-15T17:53:35.000Z",
"statusModifiedDate": "2016-07-15T17:53:35.000Z",
"statusReason": "standardFlow",
"statusReasonModifiedDate": "2019-08-20T00:00:00.000Z",
"lastTransactionId": 0,
"ledgerBalanceAmount": 0,
"ledgerBalanceDate": "2016-07-15T17:53:35.000Z",
"availableBalanceAmount": 0,
"availableBalanceDate": "2016-07-15T17:53:35.000Z",
"bankAccountId": "a097b480-ba11-4645-8426-9afd79c2b47e",
"bankAuthorisation": {
"redirect": "https://www.usbank.com/"
},
"rules": [
"6442eb14-7a80-4114-8b70-7e87e31b1be0"
],
"accountant": {
"accountantManaged": true,
"accountantCompanyId": "b42079ba0-68dc-4d71-ae1c-2acd87f0a010"
},
"company": {
"ompanyId": "c56049gh0-52hj-4r82-fq5c-6jdr63f0s913",
"companyName": "Another Company",
"vatNumber": "12345678"
},
"heldTransactions": 2,
"dataProvider": "direct",
"authAlwaysRequired": false,
"requestedStartDate": "2016-06-17T00:00:00.000Z",
"lastTransactionsReceived": "2018-06-17T00:00:00.000Z",
"lastUpdatedByProvider": "2018-06-17T00:00:00.000Z",
"featureOptions": {
"autoCreateRules": false,
"allowManualUpload": false,
"allowCorrections": false
}
}
Guides
Multi-account link product demo
A guide demonstrating how Sage Intacct has integrated with multi-account link.
Bank identifier
Take a deep dive into the bank identifier field.
Recap
In this walkthrough we have looked at how a consuming application would integrate multi-account linking into their solution.
What’s next?
When additional accounts are linked and in an active state you can pull transactions into the product.