Income

The Income Summary object with income summarised and classified by type: regular, irregular or other sources (created/refreshed across up to 10 institutions)

📘

Income sources are identified based on patterns by amounts and frequency - to determine the regularity and reliability of each income source

👍

Sandbox testing the Income endpoint (independently of Affordability)

You will need to create a user and create or refresh all connections before creating a new income resource. Use the Wentworth-Smith test credentials to create a connection for our test institution AU00000 before calling the Income endpoint. See our testing section for more information.

The Affordability API returns links to Income and Expenses resources - if you use the Affordability endpoint there is no need to create an Income or Expense resource

Attributes
type	Value of this resource is "income".
id	The identifier of the income resource to be retrieved.
fromMonth	Start month for the period for which the Income summary is generated. The period of time relates to the account and transaction data used as input into the report.
toMonth	End month (usually the current month) for the period for which the Income summary is generated.
coverageDays	Number of days included in the report period.
summary	Summary totals relating to income analysis:
	regularIncomeAvg- total median regular income monthly calculated over the past 3 months for all regular sources regularIncomeYTD- total regular income so far this financial year (year to date) regularIncomeYear- total predicted regular income for this financial year year irregularIncomeAvg - total mean of irregular income monthly calculated across the whole time period for all irregular sources

📘

Our complex income algorithm uses over 50 rules to identify different types of income sources. For example, to identify a regular income source - a fortnightly salary should have a repeating pattern over a 90 day time period with regular intervals and similar amounts. Additionally, tolerances are applied based on confidence in identified income source patterns (by amount and frequency). This means that a stable pattern with a gap in payment intervals will still be considered a regular income source with the stability being less than 1.

Regular Sources
source	Source regular income (cleaned transaction description).
frequency	Enum detailing frequency regular income e.g. "bi-weekly"
	daily
	weekly
	bi-weekly (fortnightly)
	monthly
	bi-monthly (every 2 months)
	quarterly
	half-year
irregularity	Indication of income gaps within the regular income series
	stability an indicative score between 0 and 1 that factors in the gaps between credits in a regular income series as well as the variation in the credit amounts. Stability scores close to 1 indicate highly stable income. Stability scores lower than 0.5 would be unusual as the series has to show a level of uniformity to be categorised as Regular Income. The calculation is based on pairing sequential credits and then conducting Fourier Transformation.
	gaps array of dates for which the expected credit is not met
ageDays	Duration regular income (number days from first to last occurrence) returned as an integer with values zero or greater
previous3Months	Summary for regular income sources for past 3 months:
	amountAvg - median regular income amount - calculated across all occurrences in last 3 months (note: median provides a more reliable amount than mean for a regular income source as it is less affected by outliers and skewed data - use variance amount to understand outliers and changeHistory to view actual credits) amountAvgMonthly- median monthly regular income amount variance - standard deviation in credits for the regular income series. The algorithm works out the Mean (the simple average of the numbers) Then for each credit: subtract the Mean and square the result. Then work out the mean of those squared differences. The variance is the square root of that.
current	Most recent data relating to regular income source:
	date - most recent regular income payment date amount - most recent regular income payment amount nextdate - predicted next occurrence for regular income (note: where the pattern has recently ceased there would be no predicted next occurrence)
changeHistory	Each amount classified as income (repeated for each income credit and ordered by most recent):
	date - date income received e.g. "2018-03-15T17:00:00" amount - amount of income for that period source - source income (cleaned transaction description).

📘

Irregular Income sources typically require repeating credits with pattern by frequency or amount across a minimum 90 day time period

Irregular Sources
source	Source irregular income (cleaned transaction description).
frequency	Frequency is "irregular"
ageDays	Duration irregular income (number days from first to last occurrence) returned as an integer with values zero or greater
amountAvg	Mean of irregular income amount - calculated across all occurrences identified.
noOccurrences	Number of instances of credits in the series.
avgMonthlyOccurence	Average (mean) number of times per calendar month the credits in the series occur.
current	Most recent data relating to irregular income source:
	date - most recent irregular income payment date amount - most recent irregular income payment amount
changeHistory	Each amount classified as income (repeated for each income credit and ordered by most recent):
	date - date income received e.g. "2018-03-15T17:00:00" amount - amount of income for that period source - source income (cleaned transaction description).

📘

Other Credit Series are series where a pattern of credit is detected but the pattern does not meet the requirements for regular or irregular income, or the income series is too old e.g. former regular income or a potential future income

Other Credit Sources
source	Source Other Credit income (cleaned transaction description).
frequency	Frequency is "other", "irregular" or a time period e.g. "bi-weekly"
age day	Duration other income (number days from first to last occurrence) returned as an integer with values zero or greater.
amountAvg	Mean of irregular income amount - calculated across all occurrences identified.
noOccurrences	Number of instances of credits in the series.
avgMonthlyOccurence	Average (mean) number of times per calendar month the credits in the series occur.
current	Most recent data relating to other income source:
	date - most recent irregular income payment date amount - most recent irregular income payment amount otherCreditLabel - description of the other credit series e.g. 'former regular income'
changeHistory	Each amount classified as income (repeated for each income credit and ordered by most recent):
	date - date income received e.g. "2018-03-15T17:00:00" amount - amount of income for that period source - source income (cleaned transaction description).

Links
links	A links object containing the following members:
	self link to the requested income resource accounts an array of accounts links

🚧

You will need to create a user and create or refresh all connections before creating the income resource.

Returns

Returns a created income resource, if the operation succeeded. Returns an error if the post failed (e.g. not supplying required properties).

Example Income object

HTTP/1.11.1 200 OK
Content-Type: application/json

{
  "type": "income",
  "id": "s55bf4",
  "fromMonth": "2018-11",
  "toMonth": "2019-11",
  "coverageDays": 394,
  "generatedDate": "2019-12-10T05:49:15",
  "summary": {
    "regularIncomeAvg": "18098.00",
    "regularIncomeYTD": "90490.00",
    "regularIncomeYear": "217176.00",
    "irregularIncomeAvg": "55.00"
  },
  "regular": [
    {
      "source": "payroll wfrms 15439393",
      "frequency": "monthly",
      "ageDays": 334,
      "irregularity": {
        "stability": "1.00",
        "gaps": []
      },
      "previous3Months": {
        "amountAvg": "18098.00",
        "amountAvgMonthly": "18098.00",
        "variance": "0.00"
      },
      "current": {
        "date": "2018-11-30T09:23:37",
        "amount": "18098.00",
        "nextDate": "2018-12-30T18:30:49"
      },
      "changeHistory": [
        {
          "source": "Payroll WFRMS 15439393",
          "date": "2018-11-30T09:23:37",
          "amount": "18098.00"
        },
        {
          ...
        }
      ]
    }
  ],
  "irregular": [
    {
      "source": "ctrlink carers 998r6789201610974v",
      "frequency": "irregular",
      "ageDays": 253,
      "amountAvg": "55.00",
      "noOccurrences": 5,
      "avgMonthlyOccurence": "1",
      "current": {
        "date": "2018-10-13T20:03:37",
        "amount": "62.00"
      },
      "changeHistory": [
        {
          "source": "CTRLINK CARERS Ref: 998R6789201610974V",
          "date": "2018-10-13T20:03:37",
          "amount": "62.00"
        },
        {
          ...
        }
      ]
    }
  ],
  "otherCredit": [
    {
      "source": "savings interest cr bal - Account 1",
      "frequency": "monthly",
      "ageDay": 335,
      "amountAvg": "110.85",
      "noOccurrences": 12,
      "avgMonthlyOccurence": "1",
      "current": {
        "date": "2019-10-29T00:00:00",
        "amount": "92.99",
        "otherCreditLabel": "regular income small amount"
      },
      "changeHistory": [
        {
          "source": "savings interest cr bal - Account 1",
          "date": "2018-10-13T20:03:37",
          "amount": "62.00"
        },
        {
          ...
        }
      ]
    }
  ],
  "links": {
    "self": "https://au-api.basiq.io/users/25c8d1ed77/income/s55bf4",
    "accounts": [
         "https://au-api.basiq.io/users/25c8d1ed77/accounts/20024b08",
         "https://au-api.basiq.io/users/25c8d1ed77/accounts/64880430",
         "https://au-api.basiq.io/users/25c8d1ed77/accounts/55bf3089",
         "https://au-api.basiq.io/users/25c8d1ed77/accounts/6jk43056"
     ]
  }
}