Skip to main content

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 \
-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

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.

attributetypesummary
first_payment_datedateDate of the first transaction in the income group.
income_typestringType 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_datedateDate of the most recent transaction in the income group.
durationstringTime elapsed between the first and last transaction of the income group.
latest_payment_descriptiondateExample description of a transaction from that income group (the most recent one).
is_activebooleanTrue if the income group is recent enough, periodic and the next expected payment date is more recent than the last account transaction date.
pay_frequencyenumTime 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_amountfloatEstimation for the next payment amount of this income group, (null if not active and not recurrent).
next_expected_payment_datedateEstimation for the next payment amount of this income group, (null if not active and not recurrent).
sourcestringName of the income source. This can refer to an employer, organization, or person. (null if no merchant/person detected in the transaction descriptions)
total_amountfloatTotal amount of income during the period between first-date and latest-date.
iso_currency_codestringCurrency of the transaction in ISO-4217 format.
transaction_idslist(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:

attributetypesummary
main_income_sourcestringThe main income source of an IncomeReport.
main_income_typestringThe main income type of an IncomeReport; see income_type in the Response table above.
total_incomefloatTotal amount of income, including earned, passive, and possible.
earned_incomefloatTotal amount of earned income.
passive_incomefloatTotal amount of passive income.
possible_incomefloatTotal amount of possible income.
earned_income_sourceslist(string)A list of sources for earned income.
passive_income_sourceslist(string)A list of sources for passive income.
possible_income_sourceslist(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.