PFM account aggregation use case
Users often find themselves with multiple accounts and relationships at several financial institutions. Personal Financial Management (PFM) solutions need to gather all of this information in one place to provide an understanding of a consumer’s financial condition. This creates a need for secure and reliable account aggregation services. The aggregation must seamlessly consolidate and provide real-time access to all relevant financial data while maintaining privacy and consent.
You can solve this problem by integrating the Akoya API into your solution. The Akoya Investments (or Balances) and Transactions products offer data recipients and their users the ability to view and manage their money in a consolidated manner. These products access financial account data from a variety of financial institutions and present the collated account details to the user.
For more information, see the blog post The Expansion of Account Ownership Validation Methods.
Prerequisites
The API calls require you to have the account holder’s consent. Each data call requires the end-user’s associated id token.
- See Get authorization code for the user authorization process
- See Token to obtain the bearer token for the API calls
Retrieve investments information
The Investments product’s accounts endpoint is a standalone endpoint that supplies balance data and extended investment details along with basic account information.
Make the GET request /accounts/{version}/{providerId}
- The
{version}parameter is the Akoya major version number. Usev2. - The
{providerId}parameter is the shortened version of the bank data provider name, example,mikomofor Mikomo, our fictional provider. You can find the providerId for each bank listed under the Data providers tab of the Data Recipient Hub.
Retrieve investments curl example
curl --request GET \
--url https://sandbox-products.ddp.akoya.com/accounts/v2/mikomo \
--header 'accept: application/json' \
--header 'authorization: Bearer <id_token>'
Find accountIds of permissioned accounts
From the results of the retrieve investments call, find the accountIds of all the permissioned accounts. You can also gather associated holdings and balance details from these results. The following is an example of investments results. Your data can vary.
{
"accountId": "426444887",
"accountType": "IRA",
"accountNumberDisplay": "*****5071",
"currency": {
"currencyCode": "USD"
},
"description": "Rollover IRA",
"fiAttributes": [],
"nickname": "My IRA",
"productName": "RolloverIRA Investment Acct",
"status": "OPEN",
"balanceType": "ASSET",
"interestRateType": "FIXED",
"interestRateAsOf": "2022-04-08T08:46:14",
"lastActivityDate": "2022-04-08T08:46:14",
"brokerId": "FID",
"margin": false,
"availableCashBalance": 69746.83,
"balanceAsOf": "2022-04-08T08:46:14",
"balanceList": [
{
"balanceDate": "2022-04-07T00:00:00",
"balanceName": "Minimumequitycall",
"balanceType": "AMOUNT",
"balanceValue": 0,
"currency": {
"currencyCode": "USD"
}
},
.....
}
]
}
Retrieve and paginate through transactions
The Transactions product allows you to retrieve up to two years of an account’s transaction history to fill out the financial picture of the user. The transactions endpoint relies on the account id of the permissioned accounts that you retrieved.
Make the GET request /transactions/{version}/{providerId}/{accountId}
The {version} parameter is the Akoya major version number. Use v2.
The {providerId} parameter is the shortened version of the bank data provider name.
You retrieved the {accountId} with the retrieve investments call.
Retrieve transactions curl example
This transaction call is for accountID 5242702. It uses the default first call offset of 0 and limit of 50 transactions.
curl --request GET \
--url 'https://sandbox-products.ddp.akoya.com/transactions/v2/mikomo/5242702?offset=0&limit=50' \
--header 'accept: application/json' \
--header 'authorization: Bearer <id_token>'
Transactions results example without paging
Transaction results show historical and current transactions, transaction types, amounts, dates and descriptions. This example has less than the default limit of 50 transactions.
{
"transactions": [
{
"depositTransaction": {
"accountId": "5242702",
"transactionId": "0203300000020",
"postedTimestamp": "2020-11-25T00:00:00Z",
"transactionTimestamp": "2020-09-10T00:00:00Z",
"description": "Manual banking 11/25",
"status": "POSTED",
"amount": -51.74,
"transactionType": "TRANSFER"
}
},
{
"depositTransaction": {
"accountId": "5242702",
"transactionId": "0203300000010",
"postedTimestamp": "2020-11-25T00:00:00Z",
"transactionTimestamp": "2020-09-11T00:00:00Z",
"description": "Manual banking",
"status": "POSTED",
"amount": 51.74,
"transactionType": "POSCREDIT"
}
},
{
"depositTransaction": {
"accountId": "5242702",
"transactionId": "0203180000010",
"postedTimestamp": "2020-11-13T00:00:00Z",
"transactionTimestamp": "2020-11-13T00:00:00Z",
"description": "MOBILE PMT 3B3RTMQZBN3TOXG WEB ID: 8369744980",
"status": "POSTED",
"amount": -200,
"transactionType": "POSDEBIT"
…………………………
}
}
]
}
Transaction pagination
An account’s transaction history often exceeds the 50 transaction limit of the initial API call. Pagination links at the top of the result link to the additional transactions. Pagination uses offset, limit, and time parameters to structure data retrieval. Use these links to make additional API calls and access all of the records you need to complete your user’s financial picture. For more information, see transactions pagination.
Repeat these steps for additional accounts and financial institutions
You will need to repeat these basic steps for each financial institution your user has included and for each account at those financial institutions. Financial institutions are designated by the providerId in step 2. Individual accounts are designated by the accountId in step 3.
Updated 6 days ago