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
- Python SDK
$ 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
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.