logo

Knowledge Base

Connecting Accounts

How Does Quovo Get Data?

Unlike other aggregators, Quovo uses multiple methods to get data, including APIs, file downloads, and CSV parsing. Our system handles any and all retrieval points in order to get the richest, most usable data in the industry. Over 90% of data on Quovo today is direct, extracted through structured feeds from institutional channels. We work directly with financial institutions in order to ensure sustainable, reliable connectivity between them and our platform, day in and day out.

What Happens if a Connection “Breaks”?

For ongoing syncs (such as our account aggregation product), connections may be interrupted by any “nongood” status.  
If and when such an interruption occurs, the connections status will change when a sync is attempted. For “nongood” statuses that require user action, following the workflows for each status will resolve them. For those statuses that do not require user action, we’ll do our best to resolve any issues ASAP.  
It’s important to keep in mind that Quovo automatically tracks the last good sync of all connections, so we have a record of when we last refreshed account data. This means that even if there’s an interruption in connectivity, we’ll automatically fetch all the data since the last successful sync before the interruption, so you won’t miss anything. It also means that for “nongood” connections, you will still have access to all the account data we have already fetched. 
In a comparative analysis of 20,000 accounts and 60 institutions against a large established competitor, Quovo maintained significantly higher uninterrupted connectivity, exceeding our competitor’s rates of continuous syncing and data updates at over 90% of accounts and institutions.
How do I disable an account?
The field   is_disabled   allows you to disable an account. Setting this to ‘true’ will disable an account, which stops updated data retrieval and makes the existing data for that account unavailable to you and your users. A common use case for inactive accounts is when a connection syncs multiple accounts under the same credentials, but not all accounts are relevant (e.g., Joe’s Bank of Earth login gets access to both his checking and savings accounts; but he makes his savings account inactive because he only wants the checking account data to flow through your app).
Aggregation

How does Quovo’s Nightly Process work?

After connecting an account for the first time, the second most important part of aggregation is to continue receiving updated information daily. Quovo has a sophisticated nightly process that retrieves and normalizes new information on all of the accounts in our system. This means that there is no need for our clients to resync a connection every day. You only need to make a GET call on your /connections and you’ll see the previous day’s activity.
The nightly syncing schedule is very complex and is constantly evolving. The reason for its complexity lies in the variability of when financial institutions update information. We’re familiar with the patterns of our institutions and therefore can pinpoint the best time to sync.
It is best practice to allow Quovo to run the nightly updates instead of regularly syncing connections yourself. Otherwise you could find yourself syncing at sub-optimal times, and more importantly, you run the risk of over syncing connections. This can cause the institution to block connections. This problem can affect all clients using Quovo so we have API usage restrictions in place to prevent this kind of abuse. 

Security Identifiers

The quality of the data provided by each institution varies. Therefore, Quovo has many features to help secure the best price and symbol for your holdings. Quovo leverages a security master of thousands of securities to analyze all investment holdings. Our security master is built on top of multiple data sources, providing us with secure fallback options and a breadth of data.
If the institution provides a public ticker for an investment holding:
Quovo will return the ticker (e.g., MSFT) that is provided by the institution if available. If the only public identifying information available is the CUSIP, we will use that for the   symbol   field. This helps to maintain consistency in pricing across thousands of institutions by applying a single end-of-day price to all public securities. 
If the institution does not provide a public ticker and we can’t recognize it:
If a security is not publicly listed and not recognized in our security master, the   symbol   field may return a Quovo-generated symbol. These symbols can be shared across multiple accounts so long as the   institution   and the   symbol_name   are the same. Here are the two types of Quovo-generated symbols:
FI Symbol
UN Symbol

Ticker Sleeves

All “FI” and “UN” symbols may also have what we call a ticker sleeve. A ticker sleeve is represented at the end of the symbol as a forward slash with a number (ie “UN:294DE44/1”). 
The purpose of a ticker sleeve is to identify groups of “FI” or “UN” tickers that have the same symbol_name but different underlying pricing structures. So a security with the symbol “UN:294DE44/1” and “UN:294DE44/2” have the same   symbol_name   but different pricing. This is common in mutual funds which have multiple pricing structures.

Proxy Tickers

For both “FI” and “UN” symbols, Quovo can offer up “proxy symbols,” which are public symbols that represent a close match to the unrecognized symbol, based on our analysis of multiple attributes such as pricing, holding name, and asset classification. We also provide a confidence score that will let you know how accurate we believe our prediction is.
  •   proxy_symbol  : the public ticker that represents Quovo’s closest match to the unrecognized holding. Proxy symbols are only available for unknown (“UN:”) or institution-specific (“FI:”) symbols
  •   proxy_confidence  : The level of confidence in the accuracy of the proxy_symbol. Confidence levels are split into four tiers: “Very High,” “High,” “Moderate,” and “Low.” These tiers can help you decide whether you should use the proxy_symbol, or ignore it due to its low confidence level.

Canceled and Pending Transactions

Cancel Transactions

Cancel transactions occur when existing transactions are substantially updated or completely removed by the financial institution. Instead of modifying the original transaction, Quovo generates a new cancel transaction which reverses the original transaction. You’ll be able to recognize all cancel transactions by looking for the   is_cancel  : true flag. 
Sometimes, a transaction can have new, updated transaction details, in which case we need to discard the old and bring in the new. On the day that the new transaction is available, we will send both a cancel transaction to cancel out the old transaction and a brand new transaction with the changes. You should treat the new transaction like you would any other: without any ties to the cancel transaction or the original one.
Note: Original transactions are not removed from an account’s list of transactions.
A cancel transaction has its own unique transaction ID and includes information that allows you to identify the original transaction. Most of the cancel transaction’s fields will match those in the original transaction, aside from those noted below:
  •   is_cancel  : true
  •   memo  : “QPC CANCEL [Original Transaction ID] [Original Transaction memo]
  •   type  : “X”
  •   subtype  : “QPC”
  •   quantity  : original quantity * -1
  •   value  : original value* -1
By negating the quantity and value fields, we can auto-reconcile the original transaction. For instance, to cancel out a buy into a security (positive quantity, negative value), the cancel transaction will have a negative quantity and a positive value.

Pending Transactions

Note: Pending transactions can be turned on or off depending on your use case. Please contact us to turn it on, as it is OFF by default. It is important to note that pending transactions do not have an ID.
Pending transactions are cash transactions that have not yet settled in a bank account. Investment transactions that settle after their trade date (“T+3”) for example, are not included in this definition.
Since pending transactions are temporary, they are treated a bit differently from normal transactions. Quovo will clear out and reinsert all pending transactions on every successful account sync. Therefore, pending transactions will not have an ID and should not be treated like a normal transaction. It is considered best practice to clear out all pending transactions and to reinsert them on a daily basis. Once a transaction has settled, it will flow through into the account like any other transaction.  

Webhooks

Using Webhooks

Webhooks are custom HTTP callbacks. They allow you to subscribe to specific “events” and receive a related JSON payload at a specified URL every time that “event” happens. For example, you can subscribe to Connection events and get notified every time a user adds a new  connection . Quovo limits API users to four registered webhooks. As we expand our available webhook events, this limit will increase.
To register for a new webook, send a POST request to the /webhooks endpoint. The important fields when sending the request to register a new webhook are the   events  , the   name  , the   secret  , the   url  , and the   version  . The webhook  events   specify which webhook event you would like to subscribe to. You can find a full list of webhook events here. The  name   of the webhook is what you are calling this specific webhook. The   secret   is a string used to calculate the signature on webhook deliveries, which ensures the incoming payload is coming from Quovo. The   url   is where you would like the webhook to POST data to. It must follow HTTPS protocol. The   version   indicates if you would like the webhook in an API v3 or API v2 format. The default value is “2.0,” therefore you should pass “3.0” if you are using API v3.
A sample request to subscribe to all webhook events is shown below:
curl -X POST \
-H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
-H "Content-Type: application/json" -d '{"name": "main_webhook", "url": "https://quovo.com/webhooks", "secret": "mysupersecretsecret"}' \
"https://api.quovo.com/v3/webhooks"
You should always verify webhook payloads. There are two important fields in these payloads, the   webhook-event  , which corresponds to the specific event that triggered the webhook, and the   webhook-signature  , a signature in the payload that verifies the request was sent by Quovo. The signature is an HMAC hexdigest of the entire payload body, using your registered secret as the key and SHA-1 encryption. To verify a payload, calculate the signature using the payload’s body and the   secret   you registered with the webhook. If the signature you calculate matches the signature in the request header, the POST request was genuinely sent by Quovo.
Here is a sample webhooks signature verification function in Python. The   secret   of this function is “mysupersecretsecret.”
import hmac
from hashlib import sha1

def verify_payload(payload, secret, signature):
  hashed = hmac.new(secret, payload, sha1)
  return hmac.compare_digest(hashed.hexdigest(), signature)
And here is a sample webhook payload:
{
    "connection": { 
        "config_instructions": null,
        "created": "2016-03-28T15:40:54.463",
        "id": 877247,
        "institution_id": 2,
        "institution_name": "Fidelity",
        "is_disabled": false,
        "last_good_sync": "2016-03-28T15:40:54.463",
        "last_sync": "2016-03-28T15:40:54.463",
        "status": "good",
        "user_id": 162703,
        "username": "quovo_test_user",
        "value": 8692.926
    },
    "action": "started",
    "event": "sync",
    "sync": {
        "connection_id": 877247,
        "config_instructions": null,
        "progress": {
            "message": "queued",
            "percent": 0.0,
            "state": "queued"
        },
        "status": "syncing"
    },
    "user": {
        "email": null,
        "id": 162703,
        "name": "Quovo Testuser",
        "username": "quovo_test_user",
        "value": 18321.23
    }
}
These response fields are the response fields for the connection, sync, and user objects. You can find more information about these objects in the connecting accounts section.