logo

Balances & Holdings

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
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  .