> ## Documentation Index > Fetch the complete documentation index at: https://docs.mx.com/llms.txt > Use this file to discover all available pages before exploring further. # List insights by account > Use this endpoint to list all insights associated with an account GUID. ## OpenAPI ````yaml /openapi/platform-api/v20250224.yaml get /users/{user_guid}/accounts/{account_guid}/insights openapi: 3.0.0 info: contact: name: MX Platform API url: https://www.mx.com/products/platform-api description: > The MX Platform API is a powerful, fully-featured API designed to make aggregating and enhancing financial data easy and reliable. It can seamlessly connect your app or website to tens of thousands of financial institutions. ## Version Header Versions are set in the `Accept-Version` header of API requests. Version numbers correspond with the date associated with that version. The example below uses the version `v20250224`. ``` -H 'Accept: application/json' -H 'Accept-Version: v20250224' ``` --- title: MX Platform API version: '20250224' servers: - url: https://int-api.mx.com - url: https://api.mx.com security: - basicAuth: [] tags: - name: authorization - name: accounts description: > The Accounts endpoints represent a user's checking, savings, mortgage, 401(k), or other types of accounts held by a financial institution. An account belongs to a `member`, which represents the user's overall relationship with a particular financial institution. A checking account may be just one part of a larger relationship that could also include a car loan and a savings account. Accounts—and the transactions associated with them—are updated every 24 hours, unless the associated `user` is disabled. You can also create manual accounts. Since a manual account has no credentials tied to the member, the account will never aggregate or include data from a data feed. All manual accounts are automatically created under the Manual Institution member. - name: ach return description: > The features documented here are in a beta state, and this documentation is considered draft material subject to frequent change. Using our Platform API, you can securely submit ACH Returns to reduce your ACH return rates and automate your ACH return process. You can query the status and outcomes of your submitted ACH returns to track progress and access resolution details. - name: budgets description: > Use these endpoints to create and manage budgets for your end users. You can create a budget for a specific category or autogenerate a budget for several categories based on existing transactions. Each budget has a `category_guid`, relating to one of the [categories](/api-reference/platform-api/v20250224/categories#default-categories-and-subcategories). - name: categories description: > A `transaction` can have its `category` set to one of MX’s default categories or a custom category for a specific `user`. See [Default Categories and Subcategories](/api-reference/platform-api/v20250224/categories#default-categories-and-subcategories) for a complete list. - name: deprecated - name: goals description: > Use these endpoints to create and manage goals for a `user`. You can also reposition goals to adjust their priority levels. Every goal has a track type and a meta type. The [track type](/api-reference/platform-api/v20250224/goals#goal-track-type) is the overall classification of the goal (debt, savings, retirement, or emergency fund) while the [meta type](/api-reference/platform-api/v20250224/goals#goal-meta-type) is the specific classification (like college, house, vacation, and so on). - name: insights description: > Use these endpoints to build customizable user experiences in UIs powered by our Financial Insights data. With Financial Insights, your users will receive personalized insights based on their transaction history. Want to learn more about the product? See [Financial Insights](/products/experience/insights). Looking for a guide to use these endpoints? See [Build Your Own Insights UI](/products/experience/insights/integration-guides/insights-api-guide). - name: institutions description: > Institutions represent a financial institution. A single real-world financial institution may have several `institution` objects on the MX platform. For example, the mortgage division of a financial institution might use a separate system than its everyday banking division, which is different from its credit card division. For more info, see [Institutions Overview](/api-reference/platform-api/v20250224/institutions). - name: investment holdings description: > Investment Data Enhancement lets you connect to an end user's financial institution and retrieve cleansed and enhanced investment data. By combining investment data with retail banking information, you get comprehensive insights into customer financial behaviors, risk tolerance, and investment strategies. You can [read a user's holding](/api-reference/platform-api/v20250224/reference/investment-holdings/read-holding), [list all their holdings](/api-reference/platform-api/v20250224/reference/investment-holdings/list-holdings-by-user), or list their holdings by [account](/api-reference/platform-api/v20250224/reference/investment-holdings/list-holdings-by-account) or [member](/api-reference/platform-api/v20250224/reference/investment-holdings/list-holdings-by-member). You can also [deactivate a user](/api-reference/platform-api/v20250224/reference/investment-holdings/deactivate-user-from-investment-holdings) from the Investment Data Enhancement. This is non-billable. - name: managed data - name: members description: > Members represent the connection between an end user and a financial institution. This institution may represent your institution or another one from which MX is aggregating data. For more info, see [Members Overview](/api-reference/platform-api/v20250224/members). - name: merchants description: > Merchants are representations of a transaction’s origin. For example, if you buy a coffee at Starbucks, the transaction merchant will be `Starbucks`. Use the `merchant_guid` and a `merchant_location_guidon` any `transaction` object to access Merchant endpoints for details like the merchant’s name, logo URL, website, street address, and more. - name: microdeposits description: > Microdeposits is an additional verification method that allows you to verify account details and navigate the process of using microdeposits and the automated clearing house (ACH) system. Make two, small ACH deposits into a consumer's account using the provided account and routing number. You can then require that the end user confirm the exact amount of each deposit to verify that they own the account and meet NACHA’s account verification. For more info, including process flows, setting block lists, and more, see [Microdeposits](/products/connectivity/microdeposits). - name: monthly cash flow profile - name: notifications description: > You can only use notifications endpoints if you’re using the MX mobile application. All notifications created through the API will be of notification type `API_NOTIFICATION`, channel `PUSH`, and will not be associated to an entity. No other channels are supported. The read and list endpoints can return any notification associated with the `user`, including notifications created by MX for other channels besides `PUSH`. - name: processor token - name: rewards - name: spending plan description: > Use the Spending Plan endpoints to create your own version of our [Spending Plan Widget](/products/experience/pfm/legacy-widget-overviews/spending-plan), which helps end users track their spending throughout the month. To understand key terms and how to best use these endpoints, see [Build Your Own Spending Plan UI](/products/experience/pfm/integration-guides/build-your-own-spending-plan-ui). - name: statements description: > With Statements, you can retrieve a user's monthly account statements in PDF format. This data can be used for solutions like personal financial management or risk analysis. - name: taggings description: > Tags and taggings are two resources in the MX Platform API that, when used together, give end users more control over organizing their transactions. A tag is a custom label that can be applied to a transaction. After you create a tag, use it for tagging. This means you should actually apply the tag to a particular transaction. Together, they're a powerful tool for personalization, customization, and money management. For a guide on creating a tag and then applying it to a specific transaction with a tagging, see [Custom Tags and Taggings](/products/experience/pfm/integration-guides/personalization/). - name: tags description: > Tags and taggings are two resources in the MX Platform API that, when used together, give end users more control over organizing their transactions. A tag is a custom label that can be applied to a transaction. After you create a tag, use it for tagging. This means you should actually apply the tag to a particular transaction. Together, they're a powerful tool for personalization, customization, and money management. For a guide on creating a tag and then applying it to a specific transaction with a tagging, see [Custom Tags and Taggings](/products/experience/pfm/integration-guides/personalization/). - name: transaction rules description: > Transaction Rules allow users to automatically recategorize or rename all similar transactions according to their preferences. This only applies to future transactions. When recategorizing or renaming a transaction, the user will be asked whether they want the new data to apply to the selected transaction or to all future transactions. If they choose to apply it to all future transactions, it will create a transaction rule which will automatically apply the changes going forward. - name: transactions description: > Transactions represent any instance in which money moves into or out of an account. This could be a purchase at a business, a payroll deposit, a transfer from one account to another, an ATM withdrawal, and so on. Transactions are created automatically when a member is successfully aggregated. Each `transaction` belongs to only one `account`. For more info, see [Transactions Overview](/api-reference/platform-api/v20250224/transactions). - name: users description: > Users represent an end user using the Platform API through your web or mobile app. Users are created by MX clients and belong to a specific [client](/products/connectivity/overview/data-architecture#resources) on the platform. - name: verifiable credentials description: > MX provides Verifiable Credential endpoints that comply with web5 standards. For more info, see [Verifiable Credentials Overview](/api-reference/platform-api/v20250224/verifiable-credentials). - name: widgets description: > Use the [Request Widget URL](/api-reference/platform-api/v20250224/reference/widgets/request-widget-url) endpoint to generate a URL that loads one of our widgets. Many request body parameters only work for some widgets. For more info, including widget types, see [Widgets Overview](/api-reference/platform-api/v20250224/widgets). paths: /users/{user_guid}/accounts/{account_guid}/insights: get: tags: - insights summary: List insights by account description: Use this endpoint to list all insights associated with an account GUID. operationId: listInsightsByAccount parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/accountGuid' - $ref: '#/components/parameters/userGuid' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/recordsPerPage' - $ref: '#/components/parameters/insightIncludes' responses: '200': content: application/json: schema: $ref: '#/components/schemas/InsightsResponseBody' description: OK components: parameters: acceptVersion: name: Accept-Version in: header required: true schema: type: string default: v20250224 example: v20250224 description: MX Platform API version. accountGuid: description: The unique id for an `account`. example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1 in: path name: account_guid required: true schema: type: string userGuid: description: The unique identifier for a `user`, beginning with the prefix `USR-`. example: USR-fa7537f3-48aa-a683-a02a-b18940482f54 in: path name: user_guid required: true schema: type: string page: description: Results are paginated. Specify current page. example: 1 in: query name: page schema: type: integer recordsPerPage: description: >- This specifies the number of records to be returned on each page. Defaults to `25`. The valid range is from `10` to `100`. If the value exceeds `100`, the default value of `25` will be used instead. example: 10 in: query name: records_per_page schema: type: integer insightIncludes: name: includes description: >- Opt in to receiving additional data on insights. Pass `?includes=localization_payload` to populate the `localization_payload` object on each insight. - When included, insights with a supported template return `localization_payload` with `is_enabled: true` and the template-specific fields populated. Unsupported templates return `localization_payload` with `is_enabled: false`. - If the parameter is omitted entirely, the `localization_payload` key is not included in the response at all (it is absent, not `null`). - Currently supported templates: `BillAmountNotStandard`, `MonthlySubscriptionAggregateV2`, `SubscriptionPriceIncrease`. This list may grow as more templates are enabled. in: query required: false example: localization_payload schema: type: string schemas: InsightsResponseBody: properties: insights: items: $ref: '#/components/schemas/InsightResponse' type: array pagination: $ref: '#/components/schemas/PaginationResponse' type: object InsightResponse: properties: active_at: description: >- The date and time when the insight was activated, represented in ISO 8601 format with a timestamp. example: '2022-01-07T12:00:00Z' nullable: true type: string client_guid: description: >- The unique identifier for the client associated with the insight. Defined by MX. example: CLT-abcd-1234 type: string created_at: description: >- The date and time the insight was created, represented in ISO 8601 format with a timestamp. example: '2025-02-13T18:08:00+00:00' nullable: true type: string cta_clicked_at: description: >- The date and time when a call-to-action was clicked, represented in ISO 8601 format with a timestamp. example: '2022-01-13T18:13:51Z' nullable: true type: string description: description: The human-readable information being delivered to the end user. example: >- Gold's Gym charged you $36.71 more this month than normal. Did you upgrade your service? nullable: true type: string guid: description: The unique identifier for the `insight`. Defined by MX. example: BET-abcd-1234 nullable: true type: string has_associated_accounts: description: Indicates whether there are accounts associated with the insight. example: false nullable: true type: boolean has_associated_categories: description: Indicates whether there are categories associated with the insight. example: false nullable: true type: boolean has_associated_merchants: description: Indicates whether there are merchants associated with the insight. example: false nullable: true type: boolean has_associated_repeating_transactions: description: >- Indicates whether there are repeating transactions associated with the insight. example: false nullable: true type: boolean has_associated_scheduled_payments: description: >- Indicates whether there are scheduled payments associated with the insight. example: false nullable: true type: boolean has_associated_transactions: description: >- Indicates whether there are transactions associated with the insight. example: true nullable: true type: boolean has_been_displayed: description: Indicates whether the insight has been shown to the end user. example: true nullable: true type: boolean is_dismissed: description: Indicates whether the insight has been dismissed by the user. example: false nullable: true type: boolean localization_payload: type: object description: >- Structured, per-template values used to render the insight description and micro_description. The shape depends on the insight `template`. Opt-in: returned only when `?includes=localization_payload` is passed (otherwise the key is absent). When the insight's template is supported, `is_enabled` is `true` and the template-specific fields are populated. When the template is not yet supported, `is_enabled` is `false`. oneOf: - $ref: '#/components/schemas/LocalizationPayloadUnsupported' - $ref: '#/components/schemas/LocalizationPayloadBillAmountNotStandard' - $ref: >- #/components/schemas/LocalizationPayloadMonthlySubscriptionAggregateV2 - $ref: >- #/components/schemas/LocalizationPayloadSubscriptionPriceIncrease micro_call_to_action: description: A short call-to-action text for prompting user engagement. example: Learn more nullable: true type: string micro_description: description: >- A shorter version (300 characters or less) of `description`. This is the insight's description we display to the end user in the Micro Widget example: Netflix charged you $5.00 more this month than normal. nullable: true type: string micro_title: description: >- A shorter version (60 characters or less) of `title`. This is the insight's title we display to the end user in the Micro Insights Widget. For example, `Price Increase` or `Paycheck Deposit`. example: Price Increase nullable: true type: string template: description: >- A short label for the type of `insight` being delivered, for example, `SubscriptionPriceIncrease` or `MonthlyCategoryTotal`. example: SubscriptionPriceIncrease nullable: true type: string title: description: >- The title for the specific `insight`, for example, `Price Increase` or `Paycheck Deposit`. example: Price increase nullable: true type: string updated_at: description: > The date and time the resource was last updated in ISO 8601 format with a timestamp. For categories, this field will always be `null` when `is_default` is `true`. example: '2025-02-13T18:09:00+00:00' nullable: true type: string user_guid: description: The unique identifier for the user. Defined by MX. example: USR-fa7537f3-48aa-a683-a02a-b18940482f54 type: string user_id: description: The unique partner-defined identifier for the user. example: u-1234 type: string type: object PaginationResponse: properties: current_page: description: The page delivered by the current response. example: 1 type: integer per_page: description: The number of records delivered with each page. example: 25 type: integer total_entries: description: The total number of records available. example: 1 type: integer total_pages: description: The total number of pages available. example: 1 type: integer type: object LocalizationPayloadUnsupported: type: object additionalProperties: false required: - is_enabled properties: is_enabled: type: boolean description: >- Whether the localization payload is populated for this insight's template. example: false enum: - false LocalizationPayloadBillAmountNotStandard: type: object additionalProperties: false required: - is_enabled - template - scenario - average_amount - current_amount - higher_or_lower - merchant_name - percentage_change - transaction_month properties: is_enabled: type: boolean description: >- Whether the localization payload is populated for this insight's template. example: true template: type: string enum: - BillAmountNotStandard scenario: type: string nullable: true description: >- The variant for this insight, used to select the appropriate localized string template. Null when the template has only one variant. example: higher average_amount: type: number example: 36.71 description: >- The average bill amount (limited to the five most recent transactions). current_amount: type: number example: 36.71 description: The triggering transaction's amount. higher_or_lower: type: string description: Whether the bill was higher or lower than usual. merchant_name: type: string description: The merchant's name. percentage_change: type: number example: 25 description: >- The percentage increase or decrease between `average_amount` and `current_amount`. transaction_month: type: string example: June 5 description: The month of the triggering transaction. LocalizationPayloadMonthlySubscriptionAggregateV2: type: object additionalProperties: false required: - is_enabled - template - scenario - amount_sum - count - date properties: is_enabled: type: boolean description: >- Whether the localization payload is populated for this insight's template. example: true template: type: string enum: - MonthlySubscriptionAggregateV2 scenario: type: string nullable: true description: >- The copy variant for this insight, used to select the appropriate localized string template. Null when the template has only one variant. amount_sum: type: number example: 36.71 description: The total value of all of those subscriptions. count: type: integer example: 3 description: >- The total number of merchants from which subscription transactions were detected for the period. date: type: string example: June 5 description: The date the beat was generated. LocalizationPayloadSubscriptionPriceIncrease: type: object additionalProperties: false required: - is_enabled - template - scenario - increase_amount - merchant_name properties: is_enabled: type: boolean description: >- Whether the localization payload is populated for this insight's template. example: true template: type: string enum: - SubscriptionPriceIncrease scenario: type: string nullable: true description: >- The copy variant for this insight, used to select the appropriate localized string template. Null when the template has only one variant. increase_amount: type: number example: 36.71 description: The amount the subscription price increased. merchant_name: type: string description: The merchant name associated with the subscription. securitySchemes: basicAuth: scheme: basic type: http description: > To authenticate with the Platform API, include your Base64-encoded `client_id` and `api_key` in the Authorization header of every request: ``` -H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' ``` ````