Income Check

Ntropy Income Check allows you to extract the details about all income sources of your customers from their bank transactions. To get an accurate result, it is important to connect all bank accounts that belong to a user.

Getting Started

The first step is to add the entire transaction history of an account holder using Ntropy enrichment. If you have previously added these transactions, you do not need to add them again.

Once transactions have been added, an income report can be generated:

cURL

$ curl \
-H "X-API-KEY: <YOUR-API-KEY>" \
-H "Content-Type: application/json" \
-X POST \
https://api.ntropy.com/v2/account-holder/<account_holder_id>/income

Python SDK

from ntropy_sdk import SDK

sdk = SDK("<YOUR-API-KEY>")
income_report = sdk.get_income_report(<account_holder_id>)

You will get back the income report as a JSON object with the API and as an IncomeReport with the SDK:

[
  {
    "duration": "3 months",
    "first_payment_date": "2022-06-30",
    "income_type": "salary",
    "is_active": true,
    "latest_payment_date": "2022-09-30",
    "latest_payment_description": "GUSTO PAYROLL PAY 631475 223009",
    "pay_frequency": "monthly",
    "next_expected_payment_amount": 1186.27,
    "next_expected_payment_date": "2022-10-30",
    "source": "Gusto",
    "total_amount": 4745.08,
    "transaction_ids": [
      "4yp49x3tbj9mD8DB4fM8DDY6Yxbx8YP14g565Xketw3tFmg",
      "4yp49x3tbj9mD8DB4fM8DDY6Yxbx8YP14g565Xketw3tFmf",
      "4yp49x3tbj9mD8DB4fM8DDY6Yxbx8YP14g565Xketw3tFmd",
      "4yp49x3tbj9mD8DB4fM8DDY6Yxbx8YP14g565Xketw3tFms"
    ]
  },
  {
    "duration": "0 days",
    "first_payment_date": "2022-07-09",
    "income_type": "interest and dividends",
    "is_active": false,
    "latest_payment_date": "2022-07-09",
    "latest_payment_description": "Credit Interest",
    "pay_frequency": null,
    "next_expected_payment_amount": null,
    "next_expected_payment_date": null,
    "source": "N/A",
    "total_amount": 1.09,
    "transaction_ids": [
      "tw3tFmn4yp49x3tbj9mD8DB4fM8DDY6Yxbx8YP14g565Xkh"
    ]
  }
]

Each output field within the response is explained below.

attribute	type	summary
first_payment_date	date	Date of the first transaction in the income group.
income_type	string	Type of income. Can be one of: child support - passive income for child support social security - passive social security payments in the US unemployment - unemployment benefits long term rent - passive income from property rental via lease agreements (residential housing, commercial facilities, etc.) short term rent - passive income from short-term property rental (e.g. Airbnb) interest and dividends - passive income from holding cash and stocks retirement funds - passive income, including pension, roth IRAs, 403b, 457b, etc. investment - income from investments and trading of stocks and cryptocurrencies ecommerce - income from selling goods online through ecommerce platforms (Ebay, Shopify, etc.) salary - earned income from regular payroll with employer freelance - earned income from freelance activities (Upwork, Twitch, etc.) rideshare and delivery - earned income from ridesharing and food delivery services (Uber, Doordash, etc.) possible income - please verify - income type could not be determined with high enough certainty (see below)
latest_payment_date	date	Date of the most recent transaction in the income group.
duration	string	Time elapsed between the first and last transaction of the income group.
latest_payment_description	date	Example description of a transaction from that income group (the most recent one).
is_active	boolean	True if the income group is recent enough, periodic and the next expected payment date is more recent than the last account transaction date.
pay_frequency	enum	Time between transactions in this income group; weekly, bi-weekly, monthly, bi-monthly, quarterly, semi-yearly, yearly, other. If no detected periodicity, this field is null. (other - not a common frequency/periodicity, ex: every 20 days) Note that there may be miscellaneous transactions within an income group (bonuses, refunds, reversals, adjustments, bank verifications, etc.) that are outside of the this pay frequency.
next_expected_payment_amount	float	Estimation for the next payment amount of this income group, (null if not active and not recurrent).
next_expected_payment_date	date	Estimation for the next payment amount of this income group, (null if not active and not recurrent).
source	string	Name of the income source. This can refer to an employer, organization, or person. (null if no merchant/person detected in the transaction descriptions)
total_amount	float	Total amount of income during the period between first-date and latest-date.
iso_currency_code	string	Currency of the transaction in ISO-4217 format.
transaction_ids	list(string)	Ids of transactions that belong to this income group.

Additional Methods

The Ntropy SDK provides additional methods to analyze income reports:

income_report.to_df()

returns a Pandas DataFrame object with a list of all income sources for the account holder

      amount first_payment_date latest_payment_date                      income_type             source                                   transaction_ids pay_frequency
0   22352.51            2021-03-18             2022-08-02  possible income - please verify  City of Wannasee   [31821657-f370-48a5-9836-87cbbaf03e22, b3445ec...     bi-weekly
1   12633.96            2021-05-07             2022-07-12              government benefits                N/A  [31676a30-6bbb-4c68-4739-0ag72192d3d1, 3a89a36...         other

income_report.summarize()

returns an IncomeSummary object with the following attributes:

attribute	type	summary
main_income_source	string	The main income source of an IncomeReport.
main_income_type	string	The main income type of an IncomeReport; see income_type in the Response table above.
total_income	float	Total amount of income, including earned, passive, and possible.
earned_income	float	Total amount of earned income.
passive_income	float	Total amount of passive income.
possible_income	float	Total amount of possible income.
earned_income_sources	list(string)	A list of sources for earned income.
passive_income_sources	list(string)	A list of sources for passive income.
possible_income_sources	list(string)	A list of sources for possible income.

Remarks

Type

If a group of transactions may represent an income, but the type is unclear, then you will see income_type: possible income - please verify. We recommend verifying each such income group with the owner of the account.

Source

When there is no identifiable source associated with an income group or we cannot identify one with sufficient certainty, you will get null returned as the source. In some cases, such as a recurring wire transfer, null does not represent low confidence; the specified income group simply does not contain an organization or person that can be marked as the source.

Coverage

Income information can only be extracted using the transaction data provided. If there are additional accounts associated with the account holder, and if transactions from those accounts have not been added, we will not be able to provide a full picture of the user's income.