# Connection Insights Based on connected accounts you can recover user's insights, book of variables, income analysis & recurring patterns. In addition to the useful insights of [transaction categorization](/docs/transaction-categories), Pluggy offers an **Insights API** to help you gather insights about your Items' data to quickly group, filter or cluster your items according to their **financial KPIs** or their **income indicators**. ## Item financial KPIs A handy feature to quickly build intelligence over your Items is to look at their financial KPIs, which correspond to important financial statistics like cash flow, distribution of debit/credit transactions, etc. We offer an HTTP API for calculating those KPIs. Here is an example of how to use it: 1. First, [authenticate](/docs/authentication) in Pluggy API to obtain an API key 2. Execute the following request ```curl curl --location --request POST 'https://insights-api.pluggy.ai/book?itemIds={your-item-id}' \ --header 'X-API-KEY: {YOUR-API-KEY}' ``` 3. Here is an example response: ```json { "id": "b3b60afc-6a76-43ae-9c94-3457ce8952b2", "status": "COMPLETED", "book": { "bankAccount": { "percentage_transactions_debit_dates_1-5_M1": null, "percentage_transactions_credit_dates_1-5_M1": null, "count_transactions_debit_dates_1-5_M1": 0, "count_transactions_credit_dates_1-5_M1": 0, "amount_transactions_debit_dates_1-5_M1": 0, "amount_transactions_credit_dates_1-5_M1": 0, "percentage_transactions_debit_dates_6-10_M1": null, "percentage_transactions_credit_dates_6-10_M1": null, "count_transactions_debit_dates_6-10_M1": 0, "count_transactions_credit_dates_6-10_M1": 0, "amount_transactions_debit_dates_6-10_M1": 0, "amount_transactions_credit_dates_6-10_M1": 0, "diff_transactions_net_amount_M1": 0, "count_transactions_credit_M1": 0, "count_transactions_debit_M1": 0, "min_transactions_balance_M1": null, "max_transactions_balance_M1": null, "sum_transactions_credit_M1": 0, "sum_transactions_debit_M1": 0, "ratio_transactions_creditdebit_M1": null, "ratio_inflow_commitment_M1": null, "avg_transactions_credit_M1": null, "avg_transactions_debit_M1": null, "avg_transactions_credit_balance_M1": null, "avg_transactions_debit_balance_M1": null, "max_transactions_debit_period_M1": "", "max_transactions_credit_period_M1": "", "diff_transactions_net_amount_alltime": 394, "count_transactions_credit_alltime": 7, "count_transactions_debit_alltime": 1, "min_transactions_balance_alltime": null, "max_transactions_balance_alltime": null, "sum_transactions_credit_alltime": 520, "sum_transactions_debit_alltime": 126, "ratio_transactions_creditdebit_alltime": 4.13, "ratio_inflow_commitment_alltime": 169.62, "avg_transactions_credit_alltime": 74.29, "avg_transactions_debit_alltime": 126, "avg_transactions_credit_balance_alltime": 0, "avg_transactions_debit_balance_alltime": 0, "max_transactions_debit_period_alltime": "26-31", "max_transactions_credit_period_alltime": "26-31", "ratio_inflow_commitment_trend": null }, "categories": [ { "category": "Transfers", "transactionType": "CREDIT", "accountSubtype": "SAVINGS_ACCOUNT", "M1": { "avg": null, "total": 0 }, "M2": { "avg": null, "total": 0 }, "M3": { "avg": null, "total": 0 }, "M6": { "avg": 68.5, "total": 137, "min": 59, "max": 78 }, "M12": { "avg": 68.5, "total": 137, "min": 59, "max": 78 } }, { "category": "Third party transfers", "transactionType": "CREDIT", "accountSubtype": "SAVINGS_ACCOUNT", "M1": { "avg": null, "total": 0 }, "M2": { "avg": null, "total": 0 }, "M3": { "avg": null, "total": 0 }, "M6": { "avg": 96.5, "total": 193, "min": 57, "max": 136 }, "M12": { "avg": 96.5, "total": 193, "min": 57, "max": 136 } } ], "creditCard": { "percentage_transactions_debit_dates_1-5_M1": null, "percentage_transactions_credit_dates_1-5_M1": null, "count_transactions_debit_dates_1-5_M1": 0, "count_transactions_credit_dates_1-5_M1": 0, "diff_transactions_net_amount_alltime": 0, "count_transactions_credit_alltime": 0, "count_transactions_debit_alltime": 0, "ratio_transactions_creditdebit_alltime": null, "ratio_inflow_commitment_alltime": null, "ratio_inflow_commitment_trend": null, "limit_commitment_trend": null } }, "metadata": { "itemsIds": [ "786583d9-ab31-44d9-86d4-a468e1a41168" ] } } ``` **Notes:** - `M1` represents the last month, `M2` last two months, and `M12` twelve months. - `dates_1-5` represents that it's filtered between dates in the first days of the month. `dates_16-20` represents between the day 16th and 20 both included. - `amount_200-500` represents transactions with amounts having values between 200 and 500. The book response also includes income analysis data: ```json { "status": "COMPLETED", "itemId": "b3b60afc-6a76-43ae-9c94-3457ce8952b2", "result": { "totalIncomeStatistics": { "daysCoveredWithIncome": 180, "firstIncomeDate": "2021-11-01T00:00:00", "lastIncomeDate": "2022-04-29T00:00:00", "numIncomeTransactions": 17, "averageMonthlyIncomeLast30Days": 821.51, "averageMonthlyIncomeLast90Days": 3638.51, "averageMonthlyIncomeLast180Days": 3727.7134, "averageMonthlyIncomeLast360Days": 1863.8567 }, "irregularIncomeStatistics": { "daysCoveredWithIncome": 5, "firstIncomeDate": "2021-11-01T00:00:00", "lastIncomeDate": "2022-02-01T00:00:00", "numIncomeTransactions": 2, "averageMonthlyIncomeLast30Days": 100.1, "averageMonthlyIncomeLast90Days": 0, "averageMonthlyIncomeLast180Days": 0, "averageMonthlyIncomeLast360Days": 0 }, "incomeSources": [ { "transactionDescription": "recebimento de proventos municipio de santa ines", "incomeStatistics": { "daysCoveredWithIncome": 151, "firstIncomeDate": "2021-11-30T00:00:00", "lastIncomeDate": "2022-04-29T00:00:00", "numIncomeTransactions": 7, "averageMonthlyIncomeLast30Days": 821.51, "averageMonthlyIncomeLast90Days": 821.51, "averageMonthlyIncomeLast180Days": 1017.5467, "averageMonthlyIncomeLast360Days": 508.77335 }, "aggregatedIncomeStatistics": { "averageMonthlyIncome": 941.23114, "longevity": 45, "regularity": 69, "consistency": 66 } }, { "transactionDescription": "transferencia recebida #/# # #-# pref mun santa", "incomeStatistics": { "daysCoveredWithIncome": 101, "firstIncomeDate": "2021-11-23T00:00:00", "lastIncomeDate": "2022-03-03T00:00:00", "numIncomeTransactions": 4, "averageMonthlyIncomeLast30Days": 0, "averageMonthlyIncomeLast90Days": 2733.6667, "averageMonthlyIncomeLast180Days": 2518.5, "averageMonthlyIncomeLast360Days": 1259.25 }, "aggregatedIncomeStatistics": { "averageMonthlyIncome": 2473.4756, "longevity": 27, "regularity": 47, "consistency": 42 } }, { "transactionDescription": "pix - recebido #/# #:# # rocleane pe", "incomeStatistics": { "daysCoveredWithIncome": 134, "firstIncomeDate": "2021-11-01T00:00:00", "lastIncomeDate": "2022-03-14T00:00:00", "numIncomeTransactions": 6, "averageMonthlyIncomeLast30Days": null, "averageMonthlyIncomeLast90Days": 83.333336, "averageMonthlyIncomeLast180Days": 191.66666, "averageMonthlyIncomeLast360Days": 95.83333 }, "aggregatedIncomeStatistics": { "averageMonthlyIncome": 101.36883, "longevity": 36, "regularity": 25, "consistency": 0 } } ], "totalAggregatedIncomeStatistics": { "averageMonthlyIncome": 3516.0754, "longevity": 33, "regularity": 52, "consistency": 47 } }, "createdAt": "2023-02-02T19:18:26.552Z" } ``` ## Recurrent pattern detection (BETA) We also provide a service to analyze recurrent patterns in an Item's transactions (for example, payment of services or salary deposits). Here's an example of its usage: 1. Authenticate in Pluggy API to obtain an API key 2. Execute the following request ```curl curl --location --request GET 'https://insights-api.pluggy.ai/transactions/recurrency?itemId={itemId}' \ --header 'X-API-KEY: {YOUR-API-KEY}' ``` 3. Here is an example response ```json { "itemId": "b3b60afc-6a76-43ae-9c94-3457ce8952b2", "recurrentTransactions": [ { "description": "Pagamento da fatura", "type": "DEBIT", "averageAmount": -831.4033333333333, "frequency": "MONTHLY" }, { "description": "Pb*Badoo", "type": "DEBIT", "averageAmount": 5.8999999999999995, "frequency": "WEEKLY" }, { "description": "Pagamento efetuado - TIM", "type": "DEBIT", "averageAmount": -68.04785714285715, "frequency": "MONTHLY" } ] } ```