logo

Income Summary

Income Summary
Quovo’s /incomes endpoint provides you with a robust summary of income levels, sources, and streams (for either a user or an account). The incomes endpoint is broken up into different objects, with each object providing you a different perspective on evaluating income. The   summary   object has the top level details and the   stream   object has the breakdown of a specific income stream, including its constituent   transactions   within a given time period.
Getting an Income Summary
Incomes can be requested at either the account or user level. If you’d only like to see the the income in a specific account, make a GET call to https://api.quovo.com/v3/accounts/{account_id}/incomes. If you’d like to see the income for your user, which would evaluate income across the users’ accounts on Quovo, make a GET call to https://api.quovo.com/v3/users/{user_id}/incomes.
You can also select the period for when the income is evaluated. Use the   start_date   and   end_date   parameters to pick a duration for which you want to see the income evaluation. 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, the income will be evaluated starting from the date of the earliest transaction. If no   start_date   or   end_date   are passed, then the income evaluation will default to the trailing 12 months.
Income summaries can also filter out certain transactions and income streams. To filter out income streams by length, you can use the   min_income_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 income streams by value, you can use the   min_income_value   parameter. Passing this parameter allows you to filter out income streams with values that are too small.
Here is a sample request:
curl -X GET \
    -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
    "https://api.quovo.com/v3/accounts/1760061/incomes?start_date=2016-01-01&end_date=2017-01-01"

Income Summary Response

Here is a sample response from /incomes :
{
    "incomes": {
         "summary": {
            "end_date": "2018-03-19",
            "num_transactions": 114,
            "start_date": "2017-03-19",
            "total_irregular_income": 88823.62,
            "total_regular_income": 243985.72000000003
        },
        "streams": [
            {
                "account_id": 9599336,
                "connection_id": 4742095,
                "first_date": "2017-03-27",
                "frequency": "biweekly",
                "id": 4,
                "is_payroll_agency": false,                
                "last_date": "2018-02-19",
                "mean_value": 2441.76,
                "median_value": 2485.57,
                "memo": "DIRECTDEP QUOVO INC MEMO=456123 XXXXX4321 SMITH, SUSAN",
                "num_transactions": 23,
                "num_weeks": 47,
                "payee": "Smith Susan",
                "payer": "Quovo Inc",
                "periodicity": 14.3,
                "rank": "primary",
                "stdev_value": 272.21,
                "total_value": 56160.43,
                "transactions": [
                    {
                        "currency": null,
                        "date": "2018-02-19",
                        "id": 1736244969,
                        "value": 2648.328447
                    },
                    {
                       "currency": null,
                       "date": "2018-02-04",
                        "id": 1736244875,
                        "value": 2350.693925
                    }
                    {
                        "currency": null,
                        "date": "2017-03-27",
                        "id": 1736244996,
                        "value": 2239.99142
                    }
                ],             
                "user_id": 3238719
                 }
        ]
       
    }
}

Note: The sample response above introduces the structure of the /incomes endpoint, but a typical call to the /incomes endpoint will usually return multiple income 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 user or account you are evaluating the income for. The   stream   object returns information about specific income streams, i.e., a group of related deposits from the same source over time.
Summary Object
The   summary   object includes the   start_date   and   end_date   of your chosen time frame. If you did not request the income summary for a specific start and end date, this will default to the evaluating the income over the last 12 months. The  total_regular_income   shows Quovo’s best estimate for the sum of all deposits that are considered regular income. Quovo determines income by a number of factors, including the regularity of deposits as well as information about the source and transaction memo. The   total_irregular_income   shows the sum of all of the deposits that Quovo determines are not regular or reliable income.  The sum of the   total_regular_income   and the   total_irregular_income   will give you a full picture of incomes—from regular paychecks to occasional deposits.
Stream Object
The   stream   object groups all of the deposits into recurring income streams and returns the transactions in each income stream. Income   streams   bundle together related deposits from the same source that appear at a relatively constant and similar cadence. For example, if someone receives their paycheck on the last Friday of every month, their paycheck deposits would be in the same income stream.
In a given income stream, Quovo provides top-level statistics about the stream, including the   mean_value    median_value  , and the   stdev_value   of the transactions in the stream. Using the previous example, if someone received a raise in the middle of the income evaluation period, Quovo would still group the transactions in the same income stream. However, this would increase the mean, median, and standard deviation values of the stream. Along with these calculated metrics, Quovo provides the   total_value   of the stream. Note that the the stream   id   will change between API requests.
The   stream   object also includes   payer   and   payee   information. These fields indicate the source of income, such as for the purpose of verifying employment and the recipient of the deposit. Payee should usually be the account owner, however in the case of joint accounts it may be helpful in distinguishing the specific recipient. When Quovo parses data to distill payer and payee, we analyze a number of factors, including the transaction   memo  .
While the   payer   field shows the source of income, a separate field,   is_payroll_agency  , indicates if the   payer   is a recognized payroll agency. For a given income   stream  , the   payer  ,   payee  ,  and   memo   will always be the same. This is because a stream is in part defined by a shared source of income, a shared recipient of income, and common transaction details across deposits.
The stream object also includes quantitative details 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 helps you understand the extent to which a stream contributes to the overall income. 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, the value of the deposits, and relative patterns and size in the context of an account or user. Quovo also organizes the streams in the response by rank in order to help you quickly understand the most significant sources of income. Along with the above fields, the income summary endpoint returns Quovo identifiers such as account ID as well. A full list of response fields can be found here.
The   transactions   object returns all of the transactions within a specific stream. The transaction   date  ,   value  , and the Quovo transaction   id   are included in this object.