Insights

What you can build with this

Insights turns a user's raw bank transactions into a structured financial summary — aggregated amounts per category per time window, ready to use directly in your application.

A typical output looks like this:

You choose the time window and the category scope. Insights handles the aggregation.

What the API returns

The /insightsendpoint returns pre-calculated statistics. Here is a representative response for a user, filtered to salary income over the last 3 months with a monthly breakdown:

{
  "data": [
    {
      "type": "user",
      "userId": "usr_abc123",
      "accountIds": ["acc_001", "acc_002"],
      "providers": ["ing", "rabobank"],
      "lastUpdated": "2024-11-15T08:30:00Z",
      "processing": {
        "status": "COMPLETED"
      },
      "categories": [
        {
          "id": "income/salary",
          "type": "internal",
          "statistics": [
            {
              "categoryId": "income/salary",
              "periodId": "INDIVIDUAL-MONTHS",
              "period": {
                "type": "INDIVIDUAL-MONTHS",
                "firstTransactionDate": "2024-08-01",
                "lastTransactionDate": "2024-11-14"
              },
              "transactions": {
                "count": 3,
                "totalAmount": 8742.50,
                "averageAmount": 2914.17,
                "totalPositiveAmount": 8742.50,
                "totalNegativeAmount": 0
              },
              "recurringTransactions": {
                "count": 3,
                "totalAmount": 8742.50,
                "averageAmount": 2914.17,
                "totalPositiveAmount": 8742.50,
                "totalNegativeAmount": 0
              }
            },
            {
              "categoryId": "income/salary",
              "periodId": "3-MONTHS",
              "period": {
                "type": "PERIOD",
                "unit": "months",
                "amount": 3,
                "firstTransactionDate": "2024-08-01",
                "lastTransactionDate": "2024-11-14"
              },
              "transactions": {
                "count": 3,
                "totalAmount": 8742.50,
                "averageAmount": 2914.17,
                "totalPositiveAmount": 8742.50,
                "totalNegativeAmount": 0
              },
              "recurringTransactions": {
                "count": 3,
                "totalAmount": 8742.50,
                "averageAmount": 2914.17,
                "totalPositiveAmount": 8742.50,
                "totalNegativeAmount": 0
              }
            }
          ]
        },
        {
          "id": "income/other",
          "type": "internal",
          "statistics": [
            {
              "categoryId": "income/other",
              "periodId": "3-MONTHS",
              "period": {
                "type": "PERIOD",
                "unit": "months",
                "amount": 3,
                "firstTransactionDate": "2024-08-01",
                "lastTransactionDate": "2024-11-14"
              },
              "transactions": {
                "count": 5,
                "totalAmount": 1340.00,
                "averageAmount": 268.00,
                "totalPositiveAmount": 1340.00,
                "totalNegativeAmount": 0
              },
              "recurringTransactions": {
                "count": 1,
                "totalAmount": 250.00,
                "averageAmount": 250.00,
                "totalPositiveAmount": 250.00,
                "totalNegativeAmount": 0
              }
            }
          ]
        }
      ]
    }
  ]
}

Each entry in categoriesrepresents one transaction category. Within it, statistics contains one entry per time window. Each statistic gives you the aggregated figures for that category in that period. Compare the two categories in the example. For income/salary,transactionsand recurringTransactionsare identical — all three salary payments were identified as recurring. For income/othe, there are 5 transactions totalling €1,340, but only 1 of them (€250) was flagged as recurring. The remaining €1,090 arrived as incidental deposits. If you are assessing structural income, recurringTransactions.totalAmountgives you €250 — not €1,340.

How to read the response

Time windows

Every statistic is linked to aperiodIdthat defines the time window it covers. You can request all periods at once or filter to one. Available windows include rolling periods (90 days, 3 months, 6 months, 12 months) and monthly breakdowns (one statistic per calendar month for the last 12 months). Theperiodobject on each statistic tells you the exact date range included — use this to verify how much data the aggregation actually covers.

User level vs. account level

Insights are available at two scopes:

• User level (type: user) — statistics aggregated across all connected bank accounts. Use this for a complete financial picture.

• Account level (type: account) — statistics scoped to a single account. Use this when you need to analyse one bank separately, for example to distinguish a salary account from a savings account.

Filter using the type and accountIdquery parameters.

All transactions vs. recurring

Each statistic contains two parallel sets of figures:

transactions- (all transactions in the category and period) and

recurringTransactions -(only transactions identified as recurring).

The difference matters when you want to distinguish structural patterns from incidental ones. A salary that arrives every month appears identically in both sets. A one-off payment of the same amount only appears intransactions. Use recurringTransactions

when structural regularity is what you are testing for.

Available statistics per category

For each category and period you receive:

• count — number of transactions

• totalAmount — sum of all amounts (negative for expenses)

• averageAmount — mean per transaction

• totalPositiveAmount / totalNegativeAmount — split by direction

• minAmount / maxAmount — range

Status

Insights are calculated after the full enrichment pipeline — categorisation and recurring detection — has completed for all of a user's accounts. The calculation then runs as a separate step, during which the Insights record has processing.status: PROCESSING. Once finished, it moves to COMPLETED.

Always check processing.statusbefore using the data:

The Insights calculation is triggered automatically — you do not need to initiate it. Poll the endpoint or use a webhook to detect when COMPLETED is reached.