Balances & Holdings

Like all of Quovo’s products, aggregation begins with connecting accounts. Once accounts are successfully connected and synced, you can work with balances and holdings through the https://api.quovo.com/v3/holdings endpoint. Holdings can be retrieved at a few different levels, just include the level you’re looking for in your GET request to /holdings.

https://api.quovo.com/v3/users/12345/holdings, Quovo user_id to see all holdings for an end user
https://api.quovo.com/v3/connections/123456/holdings, connection_id to see all holdings for a given connection
https://api.quovo.com/v3/accounts/1234567/holdings, account_id to see all holdings for a specific financial account

curl -X GET \
    -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
    "https://api.quovo.com/v3/accounts/12345678/holdings"

Quovo defines a holding as anything held in a financial account—securities such as stocks or mutual funds, as well as currency or cash. For cash accounts, we will return a holding with a symbol of CUR:USD. Note that foreign holdings will be returned in their local currencies.

Response Fields

The /holdings endpoint contains both the basic information about the holding as well as some Quovo specific attributes. Every holding will have the standard Quovo identifiers, such as IDs for the holding, connection, account, and user. These identifiers should help you track the holding in the Quovo ecosystem.

Note: Holding IDs will change on every successful sync, so you can only use them to track holdings between syncs.

Personal Finance (Cash Account) Holdings

Personal finance accounts (checking, savings, credit cards, loans, etc) have fewer relevant /holdings response fields. This is because they all “hold” cash and lack the complexity that come with investment positions. For these account types, the important fields are value , price , and quantity . The value of the holding is the present balance of the account, or balance without including pending transactions. If you add the value of the pending transactions to the holding value , you will have the available balance of the account. You can view a complete breakdown of the /holdings response fields in our reference docs.

Investment Holdings

Investment accounts (brokerage, IRA, 401k, etc) have more relevant fields than personal finance accounts. This is because attributes such as fluctuating prices and asset classes are more important for investment accounts. Since the first institutions that Quovo aggregated data from were investment institutions, the breadth of our offering for these institutions is a major differentiator from other aggregators.

To see the overall balance and amount of investment holdings:

Holding value is found in the value field, and is calculated by multiplying quantity and price
Quantity is the number of shares held, as reported by the financial institution
Price is the price per unit of a holding, either retrieved from the Quovo security master or as reported by the financial institution

To identify the characteristics of holdings:

Basic_asset_class is a grouping of securities that have a similar structure in the marketplace (“Equity” or “Fixed Income”)
The holding type is the vehicle that is used for the investment (e.g., “ETF” or “Bond”)

While these two fields both provide identifying information about the holding, a holding type can sometimes map to multiple values of basic_asset_class . So although a holding with a type of “Bond” will always have a basic_asset_class of “Fixed Income,” a holding type of “Mutual_Fund” can have a varying basic_asset_class based on the type of mutual fund. Check out our data dictionary for a complete list of our basic asset classes and holding types.

cost_basis will be returned only for holdings in accounts that are of account category “investments.”

Here is a sample response body of a single investment holding:

{
    "holdings": [
        {
            "account_id": 12345678,
            "basic_asset_class": "Equity",
            "connection_id": 877247,
            "currency": null,
            "forex_rate": 1.0,
            "id": 237432133,
            "price": 53.54,
            "quantity": 9.0,
            "symbol": "MSFT",
            "symbol_name": "Microsoft Corporation",
            "type": "Equity",
            "type_confidence": "Very High",
            "user_id": 162703,
            "value": 481.86
        }
   ]
}

Insurance & Annuity Holdings

Insurance Policies and Annuity contracts have the same attributes. These are represented as single contracts and therefore the quantity and price format is slightly different than a normal investment product.

We represent these contracts in the /holdings endpoint by pulling in the accumulation value (cash value)
These contracts are represented as a single holding with a quantity of 1, with a price and value equal to the accumulation value

International Currencies

Quovo’s institution coverage extends beyond the US to Canada, the UK, Australia, and Europe. Our system supports 56 currencies and automatically translates international currencies into US dollars when calculating values (contact us if you’re an enterprise who’d like to receive account data in its original international denomination). For holdings in foreign currencies, the forex_rate will tell you the exchange rate Quovo used for the conversions from a specific currency .

Go to top

Next: Transactions