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:
  1. Upload the account information;
  2. Apply operation insights-income;
  3. 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

KeyTypeDescription
average_days_between_income_paymentsFloatThe average count of days between income payments
average_monthly_discretionary_incomeFloatAverage amount of income a month that is left for spending, investing, or saving, etc
average_monthly_incomeFloatAverage monthly income
calendar_monthsIntegerCount of calendar months in the statement
calendar_months_with_incomeIntegerCount of calendar months in the statement with income
days_since_last_income_paymentIntegerCount of days since the income payment taking into account last incomplete calendar month.
debt_to_income_ratioFloatThe fraction of an account's monthly gross income that goes toward paying debt
definitionsObjectObject that is nesting expenses and income objects. Definition object holds information of income and expense definitions.
expensesArrayList of category id and title for each category in expense definition.
incomeArrayA list of category id and title for each category in income definition.
category_idStringNordigen category id of the respective income or expense category.
titleStringNordigen category title of the respective income or expense category.
income_by_categoryObjectObject 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_paymentFloatAverage transaction amount of the respective income category
number_of_income_paymentsIntegerCount of transactions under respective income category
last_incomplete_monthObjectObject that holds information of the statement's last incomplete month.
expected_remaining_incomeFloatAmount of income that is expected to be transferred within last incomplete calendar month
monthStringLast incomplete calendar month of uploaded statement
received_incomeFloatThe amount of income that is already received within last incomplete calendar month
remaining_monthly_discretionary_incomeFloatAmount of income that remains for spending in last incomplete calendar month after all mandatory expenses are paid
monthly_regularityFloatMonthly regularity of the income. Float is in interval [0,1], where 1 represents perfect regularity - income received every month
monthly_stabilityFloatMonthly stability income. Float is in interval [0,1], where 1 represents perfect stability - fixed income amount every month.
monthly_trendFloatMonthly trend income. Defined as slope of linear approximation of monthly income data.
statusStringProcessing record state
typeStringRedundant field, it will be removed in the next iteration
Jump to