---
title: "Obtain user insights based on transactions sent through /transactions/enrich"
method: POST
path: "/beta/transactions/user_insights/v1/get"
tags: ["plaid"]
---

# Obtain user insights based on transactions sent through /transactions/enrich

`POST /beta/transactions/user_insights/v1/get`

The `/beta/transactions/user_insights/v1/get` gets user insights for clients who have enriched data with `/transactions/enrich`.

The product is currently in beta.

## Request body

- TransactionsUserInsightsGetRequest — TransactionsUserInsightsGetRequest defines the request schema for `/beta/transactions/user_insights/v1/get`.
  - `client_id` string — Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body.
  - `secret` string — Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body.
  - `client_user_id` string, required — A unique client-provided `client_user_id` to retrieve insights for.

## Response `200`

OK

- TransactionsUserInsightsGetResponse — TransactionsUserInsightsGetResponse defines the response schema for `/beta/transactions/user_insights/v1/get`.
  - `user_data_overview` UserDataOverview, required — metadata for the set of insights provided in `TransactionsUserInsightsGetResponse`
    - `transaction_count` integer, required — The total number of transactions.
    - `oldest_transaction_date` string, date — The date of the oldest transaction processed to generate insights.
    - `newest_transaction_date` string, date — The date of the newest transaction processed to generate insights.
    - `days_available` integer, required — The range of days of transactions available.
    - `total_outflows` number, double, required — Sum of outflow amounts.
    - `total_inflows` number, double, required — Sum of inflow amounts.
  - `counterparty_insights` CounterpartyInsights — Insights around a user's counterparties
    - `financial_institution_insights` FinancialInstitutionInsights[] — Insights related to a user's transactions with other financial institutions, including detected account types.
      - `name` string, required — Name of the financial institution counterparty.
      - `entity_id` string, nullable — A unique, stable, Plaid-generated id that maps to the counterparty.
      - `website` string, nullable, required — The website associated with the counterparty.
      - `detected_accounts` DetectedAccount[], required — Associated accounts, detected based on the nature of transfers to/from this institution.
        - `account_type` string, nullable, required — The detected account type (depository, credit, loan, investment etc.).
        - `account_subtype` string, nullable, required — The detected subtype of the account, based on the transactions to/from the institution.
        - `transaction_count` integer, required — The number of transactions associated with this detected account type at this financial institution.
        - `oldest_transaction_date` string, date — The date of the oldest transaction associated with this detected account type at this financial institution.
        - `newest_transaction_date` string, date — The date of the newest transaction associated with this detected account type at this financial institution.
        - `newest_transaction_amount` number, double — Amount of the most recent transaction associated with this detected account type at this financial institution.
        - `total_outflows` number, double, required — Sum of outflow amounts associated with this detected account type at this financial institution.
        - `total_inflows` number, double, required — Sum of inflow amounts associated with this detected account type at this financial institution.
    - `merchant_insights` MerchantInsights[] — Insights about a user's top merchants, ranked by spend.
      - `name` string, required — The counterparty name.
      - `entity_id` string, nullable — A unique, stable, Plaid-generated id that maps to the merchant.
      - `website` string, nullable, required — The website associated with the merchant.
      - `transaction_count` integer, required — The number of transactions associated with merchant of this type.
      - `personal_finance_category_primary` string, nullable, required — The primary personal finance category associated with this merchant.
      - `personal_finance_category_detailed` string, nullable, required — The detailed personal finance category associated with this merchant.
      - `total_outflows` number, double, required — Sum of outflow amounts.
      - `total_inflows` number, double, required — Sum of inflow amounts.
  - `category_insights` CategoryInsights — Insights on a user's top personal finance categories.
    - `primary_category_insights` CategoryInsightDetails[] — List of insights of top primary personal finance categories ranked by outflow.
      - `name` string, required — Category name.
      - `transaction_count` integer, required — The number of transactions associated with this category.
      - `total_outflows` number, double, required — Sum of outflow amounts.
      - `total_inflows` number, double, required — Sum of inflow amounts.
      - `top_counterparties` string[] — The most common counterparties associated with this category sorted by outflow.
    - `detailed_category_insights` CategoryInsightDetails[] — List of insights of top detailed personal finance categories ranked by outflow.
      - `name` string, required — Category name.
      - `transaction_count` integer, required — The number of transactions associated with this category.
      - `total_outflows` number, double, required — Sum of outflow amounts.
      - `total_inflows` number, double, required — Sum of inflow amounts.
      - `top_counterparties` string[] — The most common counterparties associated with this category sorted by outflow.
  - `recurring_transactions` RecurringTransactions — Insights object for recurring transactions for `/beta/transactions/user_insights/v1/get` endpoint
    - `inflow_streams` RecurringInsightsStream[], required — An array of inflow transaction streams (e.g., income).
      - `stream_id` string, required — A unique id for the stream.
      - `description` string — The client-provided raw description of the most recent transaction in the stream.
      - `merchant_name` string, required — The merchant or primary counterparty associated with the transaction stream.
      - `oldest_transaction_date` string, date — The posted date of the earliest transaction in the stream.
      - `newest_transaction_date` string, date — The posted date of the latest transaction in the stream.
      - `average_days_apart` number, double, required — The average number of days between each of the recurring transactions.
      - `frequency` 'UNKNOWN' | 'WEEKLY' | 'BIWEEKLY' | 'SEMI_MONTHLY' | 'MONTHLY' | 'ANNUALLY' — Describes the frequency of the transaction stream. `WEEKLY`: Assigned to a transaction stream that occurs approximately every week. `BIWEEKLY`: Assigned to a transaction stream that occurs approximately every 2 weeks. `SEMI_MONTHLY`: Assigned to a transaction stream that occurs approximately twice per month. This frequency is typically seen for inflow transaction streams. `MONTHLY`: Assigned to a transaction stream that occurs approximately every month. `ANNUALLY`: Assigned to a transaction stream that occurs approximately every year. `UNKNOWN`: Assigned to a transaction stream that does not fit any of the pre-defined frequencies.
      - `transaction_count` integer — The number of transactions in this stream.
      - `transaction_ids` string[] — An array of Plaid transaction IDs belonging to the stream, sorted by posted date.
      - `average_amount` TransactionStreamAmount — Object with data pertaining to an amount on the transaction stream.
        - `amount` number, double — Represents the numerical value of an amount.
        - `iso_currency_code` string, nullable — The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts#currency-code-schema) for a full listing of supported `iso_currency_code`s.
        - `unofficial_currency_code` string, nullable — The unofficial currency code of the amount. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
      - `newest_transaction_amount` TransactionStreamAmount — Object with data pertaining to an amount on the transaction stream.
        - `amount` number, double — Represents the numerical value of an amount.
        - `iso_currency_code` string, nullable — The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts#currency-code-schema) for a full listing of supported `iso_currency_code`s.
        - `unofficial_currency_code` string, nullable — The unofficial currency code of the amount. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
      - `is_active` boolean, required — Indicates whether the transaction stream is still live.
      - `status` 'UNKNOWN' | 'MATURE' | 'EARLY_DETECTION' | 'TOMBSTONED' — The current status of the transaction stream. `MATURE`: A `MATURE` recurring stream should have at least 3 transactions and happen on a regular cadence (For Annual recurring stream, we will mark it `MATURE` after 2 instances). `EARLY_DETECTION`: When a recurring transaction first appears in the transaction history and before it fulfills the requirement of a mature stream, the status will be `EARLY_DETECTION`. `TOMBSTONED`: A stream that was previously in the `EARLY_DETECTION` status will move to the `TOMBSTONED` status when no further transactions were found at the next expected date. `UNKNOWN`: A stream is assigned an `UNKNOWN` status when none of the other statuses are applicable.
      - `personal_finance_category_primary` string — The primary category associated with the transaction stream.
      - `personal_finance_category_detailed` string — The detailed category associated with the transaction stream.
    - `outflow_streams` RecurringInsightsStream[], required — An array of outflow transaction streams (e.g., subscriptions, bills, loan payments).
      - `stream_id` string, required — A unique id for the stream.
      - `description` string — The client-provided raw description of the most recent transaction in the stream.
      - `merchant_name` string, required — The merchant or primary counterparty associated with the transaction stream.
      - `oldest_transaction_date` string, date — The posted date of the earliest transaction in the stream.
      - `newest_transaction_date` string, date — The posted date of the latest transaction in the stream.
      - `average_days_apart` number, double, required — The average number of days between each of the recurring transactions.
      - `frequency` 'UNKNOWN' | 'WEEKLY' | 'BIWEEKLY' | 'SEMI_MONTHLY' | 'MONTHLY' | 'ANNUALLY' — Describes the frequency of the transaction stream. `WEEKLY`: Assigned to a transaction stream that occurs approximately every week. `BIWEEKLY`: Assigned to a transaction stream that occurs approximately every 2 weeks. `SEMI_MONTHLY`: Assigned to a transaction stream that occurs approximately twice per month. This frequency is typically seen for inflow transaction streams. `MONTHLY`: Assigned to a transaction stream that occurs approximately every month. `ANNUALLY`: Assigned to a transaction stream that occurs approximately every year. `UNKNOWN`: Assigned to a transaction stream that does not fit any of the pre-defined frequencies.
      - `transaction_count` integer — The number of transactions in this stream.
      - `transaction_ids` string[] — An array of Plaid transaction IDs belonging to the stream, sorted by posted date.
      - `average_amount` TransactionStreamAmount — Object with data pertaining to an amount on the transaction stream.
        - `amount` number, double — Represents the numerical value of an amount.
        - `iso_currency_code` string, nullable — The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts#currency-code-schema) for a full listing of supported `iso_currency_code`s.
        - `unofficial_currency_code` string, nullable — The unofficial currency code of the amount. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
      - `newest_transaction_amount` TransactionStreamAmount — Object with data pertaining to an amount on the transaction stream.
        - `amount` number, double — Represents the numerical value of an amount.
        - `iso_currency_code` string, nullable — The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts#currency-code-schema) for a full listing of supported `iso_currency_code`s.
        - `unofficial_currency_code` string, nullable — The unofficial currency code of the amount. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
      - `is_active` boolean, required — Indicates whether the transaction stream is still live.
      - `status` 'UNKNOWN' | 'MATURE' | 'EARLY_DETECTION' | 'TOMBSTONED' — The current status of the transaction stream. `MATURE`: A `MATURE` recurring stream should have at least 3 transactions and happen on a regular cadence (For Annual recurring stream, we will mark it `MATURE` after 2 instances). `EARLY_DETECTION`: When a recurring transaction first appears in the transaction history and before it fulfills the requirement of a mature stream, the status will be `EARLY_DETECTION`. `TOMBSTONED`: A stream that was previously in the `EARLY_DETECTION` status will move to the `TOMBSTONED` status when no further transactions were found at the next expected date. `UNKNOWN`: A stream is assigned an `UNKNOWN` status when none of the other statuses are applicable.
      - `personal_finance_category_primary` string — The primary category associated with the transaction stream.
      - `personal_finance_category_detailed` string — The detailed category associated with the transaction stream.

## Other responses

- `default` — Error response

---

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