logo

Expense Summary

Expense Summary
Quovo’s /expenses endpoint provides you with summary of expense streams, along with information that helps you determine whether they are fixed, flexible, or discretionary. This endpoint is broken up into different objects, with each object providing you a different level of granularity into the user’s or account’s expenses. The   summary   object has the top-level details and the   stream   object has the breakdown of expense streams, including their   transactions  .
Getting an Expense Summary
Expenses can be requested at either the account or user level. If you’d only like to see the the expenses for a specific account,  make a GET call to https://api.quovo.com/v3/accounts/{account_id}/expenses. If you’d like to see the expenses for a user, make a GET call to https://api.quovo.com/v3/users/{user_id}/expenses. When you request the expenses for your user, Quovo calculates the expenses across all of that user’s accounts and rolls the information up into a single holistic view.
Every expense analysis is tied to a specific time period. You can use the   start_date   and   end_date   parameters to pick the window for which you want an expense analysis. The   end_date   must be later than the   start_date  , and earlier than the current date. If the   start_date   is earlier than the earliest transaction Quovo has on record for an account, expenses will be analyzed starting from the date of the earliest transaction we have. If you do not pass a   start_date   and   end_date   then the expense analysis will default to the trailing 12 months.
Expense summaries can also filter out certain transactions and expense streams. To filter out expense streams by length, you can use the   min_expense_months   parameter. When you pass a value for this parameter, Quovo will analyze the difference between the oldest and newest transactions in a stream and only return the streams that exist for a long enough window. To filter out expense streams by value, you can use the   max_expense_value   parameter. Since all expenses are negative, passing this parameter allows you to filter out expense streams that are too small.
Here is a sample request:
curl -X GET \
    -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
    "https://api.quovo.com/v3/accounts/1760061/expenses?start_date=2016-01-01&end_date=2017-01-01"

Expense Summary Response

Here is a sample response from the /expenses endpoint:
{
    "expenses": {
        "summary": {
            "end_date": "2018-02-12",
            "num_transactions": 54,
            "start_date": "2017-02-12",
            "total_irregular_expenses": 0,
            "total_regular_expenses": -46235.74
        },
        "streams": [
            {
                "account_id": 1056003,
                "category": "Bills/Utilities",
                "connection_id": 1029277,
                "first_date": "2016-11-04",
                "frequency": "monthly",
                "id": 1,
                "last_date": "2016-12-02",
                "mean_value": -89.48,
                "median_value": -87.3,
                "memo": "COMCAST 012345 SPA WEB ID: 123ACH_DEBIT",
                "num_transactions": 3,
                "num_weeks": 21,
                "periodicity": 25.5,
                "rank": "primary",
                "stdev_value": 13.07,
                "total_value": -536.91,
                "transactions": [
                    {
                        "date": "2016-11-04",
                        "id": 123456765,
                        "value": -79.96
                    },
                    {
                        "date": "2016-12-04",
                        "id": 123456764,
                        "value": -107.86
                    },
                    {
                        "date": "2017-1-04",
                        "id": 123456763,
                        "value": -86.93
                    }
                ],
                "user_id": 162703
            }
        ]
    }
}
The sample response above introduces the structure of the /expenses endpoint, but a typical call to the /expenses endpoint will usually return multiple expense streams and many transactions per stream.
The sample response is broken into two objects: the   summary   object and the   stream   object. The   summary   contains information about the date period and overall expense levels (both regular and irregular) for the account or user.  The   stream   provides information about expense streams, or categories of expenses that makes up a spending commitment within your selected time period.
Summary Object
The   summary   object includes the   start_date   and   end_date   of the period the expenses are being analyzed. If you did not request the expense summary for a specific start and end date, Quovo will default to the analyzing the expenses over the last 12 months. The   total_regular_expenses   shows Quovo’s best estimate for the sum of all transactions that are considered regular or recurring expenses. Quovo determines recurring expenses by a number of factors, including the level and regularity of spending as well as consistency in the payee or merchant. The   total_irregular_expenses   field displays the sum of all expenses over the period that are irregular or erratic based on our internal model. The sum of the   total_regular_expenses   and the   total_irregular_expenses   will be the overall spending level for an account or user.  While the expense streams stay consistent between API requests, the stream   id   will change.
Stream Object
The   stream   object identifies and returns expense streams. Expense   streams   bundle related spending based on our analysis of transaction data. In a given expense stream, Quovo provides top-level statistics about the stream. These include the   mean_value    median_value  , and the   stdev_value   of the transactions in the stream. If, for example, a user added more data to their phone plan midway into your selected time frame—and this addition increased their phone bill—Quovo would group all phone payments into one stream, but the mean, median, and standard deviation of the stream would increase. Along with these calculated metrics, Quovo provides the as well as the   total_value   of the stream. Note that the stream   id   will change between API requests.
The stream object also includes the   cashflow_category   of the expenses. Quovo uses a number of factors to determine the category of an expense, including the transaction   memo  . A full list of possible   cashflow_categories   can be found here.
The stream object also includes quantitative identifiers about the stream, including the   num_transactions   in the stream and the   num_weeks   for which the stream exists. All of the streams are given a   rank  , which determines how much a stream contributes to the overall expense profile. The values for the rank of a stream are “primary,” “secondary,” or “irregular.” Quovo uses different factors when determining stream rank, including the frequency of the stream and the value of the spending transactions. Quovo organizes the streams in the response by rank. Along with the above fields, the expense summary endpoint returns Quovo identifiers as well, such as account and connection IDs. A full list of response fields can be found here.
The   transactions   object returns all of the transactions that comprise a specific stream. The transaction   date  ,   value  , and the Quovo transaction   id   are included in this object.