---
title: "Get Behavioral Insights"
method: GET
path: "/insights/v3/behaviors"
tags: ["Behavioral Insights (New)"]
---

# Get Behavioral Insights

`GET /insights/v3/behaviors`

Enriches debit transactions with category, merchant, and location data, returning aggregated spend analytics  by category, merchant, and geography.

## Query parameters

- `entity_id` string, uuid, required
- `start_date` string, date
- `end_date` string, date

## Response `200`

OK

- object
  - `insights` BehaviorsPayload — Insights payload wrapper carrying the behavioral aggregations on debit transactions
    - `behaviors` Behaviors, required — Behavioral insights aggregating debit transactions over a period: three breakdown sections (by category, by merchant, by location), each carrying its own detected-* counts and entry breakdown.
      - `by_category` BehaviorsCategorySection, required — Category breakdown with detected-category counts.
        - `detected_primary_category_count` integer, required — Number of distinct primary categories detected.
        - `detected_secondary_category_count` integer, required — Number of distinct (primary, secondary) category combinations detected.
        - `transaction_count` integer, required — Total number of classifiable debit transactions in the analysis window.
        - `breakdown` BehavioralCategoryBreakdown[], required — One entry per (primary_category, secondary_category) combination.
          - `primary_category` string, required — Primary category name.
          - `secondary_category` string, required — Secondary category name.
          - `merchant_names` string[], required — Distinct merchant names observed within this category.
          - `merchant_count` integer, required — Number of distinct merchants in this category.
          - `total_amount` CurrencyAmount, required
            - `currency` string, required — The ISO 3 letter currency code
            - `amount` number, required — The amount of money in the currency specified.
          - `average_transaction_amount` CurrencyAmount, required
            - `currency` string, required — The ISO 3 letter currency code
            - `amount` number, required — The amount of money in the currency specified.
          - `transaction_count` integer, required — Number of transactions in this category.
          - `average_monthly_transactions` number, double, required — Average monthly transaction count across the full analysis window.
          - `average_monthly_transactions_active` number, double, required — Average monthly transaction count across months that had at least one transaction in this category.
          - `average_monthly_amount` CurrencyAmount, required
            - `currency` string, required — The ISO 3 letter currency code
            - `amount` number, required — The amount of money in the currency specified.
          - `average_monthly_amount_active` CurrencyAmount, required
            - `currency` string, required — The ISO 3 letter currency code
            - `amount` number, required — The amount of money in the currency specified.
          - `first_transaction_date` string, date-time, required — Timestamp of the first transaction in this category.
          - `last_transaction_date` string, date-time, required — Timestamp of the most recent transaction in this category.
          - `active_months` integer, required — Number of months with at least one transaction in this category.
      - `by_merchant` BehaviorsMerchantSection, required — Merchant breakdown with detected-merchant count.
        - `detected_merchant_count` integer, required — Number of distinct merchants detected.
        - `transaction_count` integer, required — Total number of classifiable debit transactions in the analysis window.
        - `breakdown` BehavioralMerchantBreakdown[], required — One entry per detected merchant.
          - `merchant_name` string, required — Merchant name.
          - `transaction_count` integer, required — Number of transactions with this merchant.
          - `total_amount` CurrencyAmount, required
            - `currency` string, required — The ISO 3 letter currency code
            - `amount` number, required — The amount of money in the currency specified.
          - `average_transaction_amount` CurrencyAmount, required
            - `currency` string, required — The ISO 3 letter currency code
            - `amount` number, required — The amount of money in the currency specified.
          - `average_monthly_transactions` number, double, required — Average monthly transaction count for this merchant across the full analysis window.
          - `average_monthly_transactions_active` number, double, required — Average monthly transaction count for this merchant across active months only.
          - `average_monthly_amount` CurrencyAmount, required
            - `currency` string, required — The ISO 3 letter currency code
            - `amount` number, required — The amount of money in the currency specified.
          - `average_monthly_amount_active` CurrencyAmount, required
            - `currency` string, required — The ISO 3 letter currency code
            - `amount` number, required — The amount of money in the currency specified.
          - `first_transaction_date` string, date-time, required — Timestamp of the first transaction with this merchant.
          - `last_transaction_date` string, date-time, required — Timestamp of the most recent transaction with this merchant.
          - `active_months` integer, required — Number of months with at least one transaction with this merchant.
      - `by_location` BehaviorsLocationSection, required — Location breakdown with detected-location count.
        - `detected_location_count` integer, required — Number of distinct locations detected.
        - `transaction_count` integer, required — Total number of classifiable debit transactions in the analysis window.
        - `breakdown` BehavioralLocationBreakdown[], required — One entry per detected location.
          - `location` string, required — Location name where transactions occurred.
          - `transaction_count` integer, required — Number of transactions in this location.
          - `total_amount` CurrencyAmount, required
            - `currency` string, required — The ISO 3 letter currency code
            - `amount` number, required — The amount of money in the currency specified.
          - `average_transaction_amount` CurrencyAmount, required
            - `currency` string, required — The ISO 3 letter currency code
            - `amount` number, required — The amount of money in the currency specified.
          - `average_monthly_transactions` number, double, required — Average monthly transaction count in this location across the full analysis window.
          - `average_monthly_transactions_active` number, double, required — Average monthly transaction count in this location across active months only.
          - `average_monthly_amount` CurrencyAmount, required
            - `currency` string, required — The ISO 3 letter currency code
            - `amount` number, required — The amount of money in the currency specified.
          - `average_monthly_amount_active` CurrencyAmount, required
            - `currency` string, required — The ISO 3 letter currency code
            - `amount` number, required — The amount of money in the currency specified.
          - `first_transaction_date` string, date-time, required — Timestamp of the first transaction in this location.
          - `last_transaction_date` string, date-time, required — Timestamp of the most recent transaction in this location.
          - `active_months` integer, required — Number of months with at least one transaction in this location.
  - `type` 'income' | 'employment' | 'cashflow' | 'credits-obligations' | 'non-credits-obligations' | 'expenses' | 'cash-balances' | 'freelancer-cashflow' | 'behaviors' | 'cashflow-patterns' | 'credit-assessments' | 'account-controls' | 'credit-obligations' — type of insight

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `404` — Not Found
- `408` — Request Timeout
- `500` — Internal Server Error

---

[API](https://skmtc.net/leantech/apis/auth.md) · [All operations](https://skmtc.net/leantech/apis/auth/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/leantech/auth/revisions/c2e46d54d886/schema)