Insights: Income

Operation keyword: insights-income

Income product verifies income source, amount, regularity, and stability. Additionally, it can project future income and trend, based on the income history.
Income product generates data points that can be used to perform income and employment verification as well as affordability checks. For more advanced use-cases, Nordigen provides other income-related data points as a part of its Credit Scoring product for Enterprise users.

Request Flow

To use this product via API, see the Endpoints section "report" and go through the following steps:

Upload the account information;
Apply operation insights-income;
Get results.

Additional params

When sending apply operation insights-income it can be customised with params argument:

period: the count of calendar months that should be subsetted for calculations. Default period is all available calendar months of uploaded statement.
currency: the main currency for output values. Default currency is the main currency of the statement’s country.
income_definition: array of categories that are associated with income. Default category list for income definition is Pension (5), Dividends received (6), Interest received(7), Cash deposit (19), Social security benefits (20), Scholarship (21), Salary (85), Bills (88), Insurance indemnity (279), Alimony and child support (358), Tax return (426), State aid payment (477), Other incoming payments from employer (733), Regular income (919), Income from rent (1151), and Work on Demand (2547).
expense_definition array of categories that are associated with mandatory expenditure. Default category list for expense definition are Groceries (26), Utilities (29), Health and pharmaceuticals (63), Mortgage (97), Alimony and child support (137), Tax and government fees (467), Invoices (494).

Response Example

For example purposes custom income definition is set to Salary and Pension, and expense definition is set to Utilities and Mortgage only.


{
  "data":{
    "attributes":{
      "insights":{
        "insights-income":{
          "average_days_between_income_payments":20,
          "average_monthly_discretionary_income":1100.10,
          "average_monthly_income":1500.00,
          "calendar_months":9,
          "calendar_months_with_income":9,
          "days_since_last_income_payment":21,
          "debt_to_income_ratio":0.05,
          "definitions":{
            "expenses":[
              {
                "category_id":"29",
                "title":"Utility services"
              },
              {
                "category_id":"97",
                "title":"Mortgage"
              }
            ],
            "income":[
              {
                "category_id":"85",
                "title":"Salary"
              },
              {
                "category_id":"5",
                "title":"Pension"
              }
            ]
          },
          "income_by_category":{
            "85":{
              "average_income_payment":1500.00,
              "average_monthly_income":1500.00,
              "days_since_last_income_payment":21,
              "median_income_payment":1500.00,
              "number_of_income_payments":9
            },
            "5":{
              "Average_income_payment":null,
              "average_monthly_income":null,
              "days_since_last_income_payment":null,
              "median_income_payment":null,
              "number_of_income_payments":null
            }
          },
          "last_incomplete_month":{
            "expected_remaining_income":1500.00,
            "month":"2020-11",
            "received_income":0,
            "remaining_monthly_discretionary_income":1702.61
          },
          "monthly_regularity":1,
          "monthly_stability":1,
          "monthly_trend":0
        }
      },
      "status":"completed"
    },
    "type":"report processing status"
  }
}

Key Descriptions

Key	Type	Description
average_days_between_income_payments	Float	The average count of days between income payments
average_monthly_discretionary_income	Float	Average amount of income a month that is left for spending, investing, or saving, etc
average_monthly_income	Float	Average monthly income
calendar_months	Integer	Count of calendar months in the statement
calendar_months_with_income	Integer	Count of calendar months in the statement with income
days_since_last_income_payment	Integer	Count of days since the income payment taking into account last incomplete calendar month.
debt_to_income_ratio	Float	The fraction of an account's monthly gross income that goes toward paying debt
definitions	Object	Object that is nesting expenses and income objects. Definition object holds information of income and expense definitions.
expenses	Array	List of category id and title for each category in expense definition.
income	Array	A list of category id and title for each category in income definition.
category_id	String	Nordigen category id of the respective income or expense category.
title	String	Nordigen category title of the respective income or expense category.
income_by_category	Object	Object of objects that holds information of descriptive statistics for each income category from requested income definition. If there are no transactions with the specific income category, then the respective fields are optional.
average_income_payment	Float	Average transaction amount of the respective income category
number_of_income_payments	Integer	Count of transactions under respective income category
last_incomplete_month	Object	Object that holds information of the statement's last incomplete month.
expected_remaining_income	Float	Amount of income that is expected to be transferred within last incomplete calendar month
month	String	Last incomplete calendar month of uploaded statement
received_income	Float	The amount of income that is already received within last incomplete calendar month
remaining_monthly_discretionary_income	Float	Amount of income that remains for spending in last incomplete calendar month after all mandatory expenses are paid
monthly_regularity	Float	Monthly regularity of the income. Float is in interval [0,1], where 1 represents perfect regularity - income received every month
monthly_stability	Float	Monthly stability income. Float is in interval [0,1], where 1 represents perfect stability - fixed income amount every month.
monthly_trend	Float	Monthly trend income. Defined as slope of linear approximation of monthly income data.
status	String	Processing record state
type	String	Redundant field, it will be removed in the next iteration