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

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"
     ]
  }
}