> ## 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.

# Build Your Own Insights UI

You can create your own insights UI using the data we provide [through our API](/api-reference/platform-api/reference/insights). This includes data such as the insight's default copy and, if available, information about the insight's related accounts, categories, merchants, scheduled payments, and transactions.

You can use this API to create UI like the following:

* A feed of all a user's insights
* Insights that appear alongside each account or transaction
* Insights that appear as banners
* Carousels with subsets of insights

<Info>
  **INFO**

  For an overview of the Financial Insights product, see the [Insights Overview](/products/experience/insights#overview).
</Info>

To create your own insights UI, you'll need to:

1. Review these [considerations](#considerations) and decide where to place the UI you build.
2. Decide what other information you want to display for each insight template, such as transaction amounts, account names, merchant logos, title copy, body copy, and more. See [Build Your Own Insights UI](#build-your-own-insights-ui) for more guidance.
3. Detect new insights using [webhooks](/resources/webhooks). Use webhooks to notify you when new insights are available, then use the API endpoints to retrieve the new insight's data and power your UI.
4. After an insight displays to the user, use the [Update Insight](/api-reference/platform-api/reference/insights) endpoint to set `has_displayed` to `true`.
5. If the user hides an insight (and if you allow the user to do so), use the [Update Insight](/api-reference/platform-api/reference/insights) endpoint to set `is_dismissed` to `true`.

## Considerations

If you choose to build your own UI for insights instead of using our widgets, here are some other important considerations:

* How will you onboard users?
* How can users provide feedback on insights?
* How can users hide insights they don't want to see?
* How do you want the user to engage with each insight?
* What zero states must you create?
* Will you use English? Unlike our widgets, English is the only supported language when using our API for insights.

## Build Your Own Insights UI

After you know where you'll place this UI for insights, take the following steps to populate the insight UI **you** create with the data **we** provide. You'll need to take these steps for every insight you have enabled and every possible scenario within each insight:

1. Choose which copy you'll use to power your UI.
   * Related API fields for full-sized copy: `body_title` and `description`.
   * Related API fields for micro copy: `micro_title` and `micro_description`.
   * See [Which Copy To Use](#which-copy-to-use) for more information.
2. Choose how users can take action on the insight. Some insights will only function as intended with a CTA. See [Actionable Insights](#actionable-insights) for more information.
3. Choose what information provided by a given insight template you want to display on your UI, such as any related accounts, categories, merchants, scheduled payments, or transactions.
   * Related fields: `has_associated_accounts`, `has_associated_categories`, `has_associated_merchants`, `has_associated_scheduled_payments`, `has_associated_transactions`.
   * If one of the previous fields returns `true`, then you can read that resource for more information. For example if `has_associated_transactions` returns `true`, then you could [List All Transactions Associated With An Insight](/api-reference/platform-api/reference/insights) to get information like the transaction `amount`, `category`, or `type`. Each resource has a similar endpoint.
4. Integrate this information into your UI using the tools or platform of your choice.

## Actionable Insights

Most of our insights are designed with one or more call-to-action (CTA) buttons that let the user take action. This allows users to follow up on the information provided in the insight. Examples of CTAs from our UI are **Transfer funds**, **View deposits**, **View more**, and **View transactions**.

For example, the `DesignateEmergencySavingsAccount` insight purely exists so users can set an emergency savings account and then contribute to the savings in that account. Without a way for users to do this, the insight loses its value.

Make sure you're enabling the user to take some relevant action and not just providing information. Some insights can have multiple scenarios.

To better understand the purpose of each CTA and the context behind it, including the default copy for all possible scenarios within that insight, see our Insight Library.

## Which Copy to Use

If the length of the copy **isn't** a concern, use the regular copy fields (`title` and `description`). This will provide the full copy for any insight and provide the user with the most information.

If the length of the copy **is** a concern, use the micro copy: `micro_title` (60 characters or less) and `micro_description` (300 characters or less). This will save space, but won't always provide the user with information they'd get from the fuller copy.

For UI that uses micro copy, we recommend you navigate the user to somewhere they can view the fuller copy, which provides the full context of an insight. For example, our Micro Widget directs users towards the Insights Widget (a full feed where users can see all their insights) when the end user taps on the Micro Widget.

## Insight Templates

These are the insight names as they appear [in the template field of the API](/api-reference/platform-api/reference/insights). You can also use these names to build functionality for a specific insight type or filter which insights you surface to users.

To determine the template name of an insight, capitalize the first letter of each word in the insight's name. "Payroll Deposit" becomes `PayrollDeposit`, "Savings Opportunity V2" becomes `SavingsOpportunityV2`, and so on.

These are the exceptions:

| Insight Name                          | Template Name                                           |
| :------------------------------------ | :------------------------------------------------------ |
| "Debt Payoff Strategies"              | `DebtPayoffStrategy`                                    |
| "Emergency Savings Milestone Reached" | `EmergencySavingsMilestone`                             |
| "HSA Deposit"                         | `HsaDeposit`                                            |
| "HSA Withdrawal"                      | `HsaWithdrawal`                                         |
| "Introduce Insights"                  | `IntroducePulse` (Insights was previously called Pulse) |
| "Microdeposits"                       | `MicroDeposits`                                         |
| "Peer-To-Peer Categorization"         | `P2pCategorization`                                     |
| "Save An Extra \$100"                 | `SaveAnExtra100Dollars`                                 |
| "Spending Plan Created"               | `SpendingPlanCreatedCelebration`                        |

<Info>
  **INFO**

  For a full list of insight descriptions, triggers, default copy, and more, see our [Insights Library](/products/experience/insights/library).
</Info>