DOCUMENTATION
Guides
Recipient login

PFM account aggregation use case

Suggest Edits

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.

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. Use v2.
  • The {providerId} parameter is the shortened version of the bank data provider name, example, mikomo for 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.


Need help?

Check out our Developer Community, or visit the Support Center in the Data Recipient Hub.

Looking for provider nuance documentation?

All provider nuance documentation is available in the Data providers section in the Data Recipient Hub.

Still stuck?

For all production issues, submit a support ticket through the Data Recipient Hub. Our support team is standing by 24/7. Questions and non-production issues will be answered during business hours.

Updated 3 months ago