---
title: "Get Income"
method: POST
path: "/insights/v2/income"
tags: ["Income"]
---

# Get Income

`POST /insights/v2/income`

`Get Income` endpoint provides essential income verification data for credit decisioning and underwriting processes. This API analyzes transaction history to produce reliable income insights for a specific borrower identified by their `entity_id`.

The API returns comprehensive income information including categorization by source (salary vs. non-salary), monthly income patterns, and statistical analysis that helps lenders accurately assess an applicant's ability to pay. These insights can be used for:

- Verifying user stated income on loan applications
- Calculating debt-to-income ratios with precision
- Identifying income stability and irregularities
- Supporting automated credit decisioning systems
- Reducing manual verification workloads in underwriting

Use this endpoint to streamline credit underwriting workflows, reduce time-to-decision, and make more informed lending decisions based on verified financial data.

## Query parameters

- `async` boolean

## Request body

- IncomeVerificationRequestBody
  - `entity_id` string, uuid, required — The `entity_id` you are querying for. The entity needs to have permissions `accounts` and `transactions`.
  - `start_date` string, date — The start date in UTC (in the format YYYY-MM-DD) you want to query transactions for. If not provided, we will default to 6 months before now.
  - `estimated_monthly_income` number — Monthly income for the user that you have gathered from another source (e.g.: reported by the user).
  - `income_type` 'SALARY' | 'NON_SALARY' | 'ALL'

## Response `200`

OK

- object
  - `insights` IncomeVerificationResponsePayload
    - `salary` IncomeCategoryPayload
      - `currency` string — Currency of the account
      - `total` IncomeTotal
        - `amount` number — The total amount of transactions
        - `count` integer — The total number of transactions within the time period.
        - `last_date_time` string, date-time — End date for transactions range
        - `first_date_time` string, date-time — Start date for transactions range
        - `average_monthly_amount` number — The average of all transaction amounts per month within the time period.
        - `average_monthly_count` number — The average number of transactions per month within the period.
        - `average_monthly_received_value` number — The average received value calculated as total amount divided by the count of months that had income (excluding zero months).
        - `maximum_monthly_amount` MonthlyAmount
          - `month` integer — The transaction month
          - `year` integer — The transaction year
          - `amount` number — The transaction amount
        - `minimum_monthly_amount` MonthlyAmount
          - `month` integer — The transaction month
          - `year` integer — The transaction year
          - `amount` number — The transaction amount
      - `monthly_totals` IncomeMonthlyTotal[]
        - `month` integer — The month of the reporting period
        - `year` integer — The year of the reporting period
        - `amount` number — The total amount of transactions in the Month
        - `count` integer — Number of transactions in the month
        - `is_month_complete` boolean — Indicates whether the data for this month is complete
      - `transactions` IncomeTransaction[]
        - `account_id` string, uuid, required — The account ID associated with the transaction
        - `transaction_id` string, required — The unique transaction identifier
        - `transaction_information` string, required — Additional information about the transaction
        - `booking_date_time` string, date-time, required — The date and time when the transaction was booked
        - `amount` number, required — The transaction amount
        - `income_source` IncomeSourceDetails, nullable
          - `type` 'EMPLOYMENT' | 'RETIREMENT' | 'HOUSING_BENEFIT' | 'GIG_ECONOMY' | 'UNEMPLOYMENT' | 'RENTAL' | 'TRANSFER_FROM_OWN_APPLICATION' | 'STUDENT_STIPEND' | 'INVESTMENTS' | 'CITIZEN_ACCOUNT' | 'SOCIAL_SECURITY' | 'SIDE_BUSINESS' | 'BONUS' | 'CASH_DEPOSIT' — Classification of income source type (combined enum for all income sources)
          - `name` string — The name of the employer or the source of the incoming transaction if available
      - `income_factors` IncomeFactors
        - `periods` IncomeFactorsPeriod[] — Array of income periods with their respective statistics
          - `period` string — The time period
          - `income_variation` number — The variation in income for this period
          - `average_income` CurrencyAmount
            - `currency` string, required — The ISO 3 letter currency code
            - `amount` number, required — The amount of money in the currency specified.
        - `delta_min_max` number — Ratio of the maximum salary amount to minimum salary amount
        - `average_monthly_income_change` number — Average of Percentage Change Month on Month within the time period.
    - `non_salary` IncomeCategoryPayload
      - `currency` string — Currency of the account
      - `total` IncomeTotal
        - `amount` number — The total amount of transactions
        - `count` integer — The total number of transactions within the time period.
        - `last_date_time` string, date-time — End date for transactions range
        - `first_date_time` string, date-time — Start date for transactions range
        - `average_monthly_amount` number — The average of all transaction amounts per month within the time period.
        - `average_monthly_count` number — The average number of transactions per month within the period.
        - `average_monthly_received_value` number — The average received value calculated as total amount divided by the count of months that had income (excluding zero months).
        - `maximum_monthly_amount` MonthlyAmount
          - `month` integer — The transaction month
          - `year` integer — The transaction year
          - `amount` number — The transaction amount
        - `minimum_monthly_amount` MonthlyAmount
          - `month` integer — The transaction month
          - `year` integer — The transaction year
          - `amount` number — The transaction amount
      - `monthly_totals` IncomeMonthlyTotal[]
        - `month` integer — The month of the reporting period
        - `year` integer — The year of the reporting period
        - `amount` number — The total amount of transactions in the Month
        - `count` integer — Number of transactions in the month
        - `is_month_complete` boolean — Indicates whether the data for this month is complete
      - `transactions` IncomeTransaction[]
        - `account_id` string, uuid, required — The account ID associated with the transaction
        - `transaction_id` string, required — The unique transaction identifier
        - `transaction_information` string, required — Additional information about the transaction
        - `booking_date_time` string, date-time, required — The date and time when the transaction was booked
        - `amount` number, required — The transaction amount
        - `income_source` IncomeSourceDetails, nullable
          - `type` 'EMPLOYMENT' | 'RETIREMENT' | 'HOUSING_BENEFIT' | 'GIG_ECONOMY' | 'UNEMPLOYMENT' | 'RENTAL' | 'TRANSFER_FROM_OWN_APPLICATION' | 'STUDENT_STIPEND' | 'INVESTMENTS' | 'CITIZEN_ACCOUNT' | 'SOCIAL_SECURITY' | 'SIDE_BUSINESS' | 'BONUS' | 'CASH_DEPOSIT' — Classification of income source type (combined enum for all income sources)
          - `name` string — The name of the employer or the source of the incoming transaction if available
      - `income_factors` IncomeFactors
        - `periods` IncomeFactorsPeriod[] — Array of income periods with their respective statistics
          - `period` string — The time period
          - `income_variation` number — The variation in income for this period
          - `average_income` CurrencyAmount
            - `currency` string, required — The ISO 3 letter currency code
            - `amount` number, required — The amount of money in the currency specified.
        - `delta_min_max` number — Ratio of the maximum salary amount to minimum salary amount
        - `average_monthly_income_change` number — Average of Percentage Change Month on Month within the time period.
  - `type` 'income' | 'employment' | 'cashflow' | 'credits-obligations' | 'non-credits-obligations' | 'expenses' | 'cash-balances' | 'freelancer-cashflow' | 'behaviors' | 'cashflow-patterns' | 'credit-assessments' | 'account-controls' | 'credit-obligations' — type of insight

## Other responses

- `202` — Accepted (Asynchronous request)
- `400` — Bad Request
- `404` — Entity not found
- `500` — Internal Server Error

---

[API](https://skmtc.net/leantech/apis/auth.md) · [All operations](https://skmtc.net/leantech/apis/auth/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/leantech/auth/revisions/c2e46d54d886/schema)