> ## 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. # Integrate using MX's Connect Widget By the end of this guide, you'll be able to connect a user to their financial institution, resolve connection errors, and retrieve financial data using the Platform API and [Connect Widget](/connect). **LOOKING FOR PLATFORM V2011101 GUIDES?** If you're using Platform API v2011101, see [Legacy Guides](/other/legacy-connectivity-guides). ## Prerequisites Before using this guide, ensure the following: * You've signed up for the Client Dashboard and can access your API keys * Your IP addresses are whitelisted in the Client Dashboard * Users exist on the MX system or you've [created a user](/products/connectivity/overview/connectivity-integration-guides/#creating-users) * You have [registered for OAuth](/resources/oauth-guide/#registration), unless you're using our test institution * You have set up how you'll [send held data](/products/connectivity/overview/held-data/) to MX (if your institution has held data) ## 1. Get the Widget URL To open the Connect Widget, you'll use the [Request Widget URL](/api-reference/platform-api/reference/request-widget-url) endpoint to retrieve a unique URL. The parameters you set in this request determine how the widget behaves. **INFO** The URL expires after ten minutes or upon first use, whichever occurs first. You'll need to obtain a new URL each time the page loads or reloads. In this request, set `widget_type` to `connect_widget` and `data_request.products` to include the products you want to aggregate. **Considerations** The products you set in your widget URL request (through the `data_request.products`) determine what data will be aggregated and which institutions appear in the widget search results. You can define the products using the following values. **NOTE** Balance data is always included and doesn't need to be set. | Product | Value | | :--------------------------- | :---------------------- | | Instant Account Verification | `account_verification` | | Account Owner Identification | `identity_verification` | | Account Aggregation | `transactions` | | Extended History | `transaction_history` | | Statements | `statements` | | Investments | `investments` | | Rewards | `rewards` | **INFO** Not every field will populate for each product, as data availability depends on what the institution provides. Specifying multiple products restricts the widget to show only institutions that support **all** the requested products. This filtering affects conversion in the following ways: * Fewer Available Institutions: Many institutions support only one product. More products requested means fewer institutions displayed to users. For example, requesting both `account_verification` and `identity_verification` will only show institutions that are capable of providing both products. * OAuth Consent Requirements: For OAuth institutions, users must grant permission for all requested products. If they decline any permission, the connection will fail and they'll need to restart the OAuth flow. Balance your data needs against potential reduction in available institutions and connection success rates. ```shell Request theme={null} curl -i -X POST 'https://int-api.mx.com/users/{user_guid}/widget_urls' \ -u 'client_id:api_key' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' \ -H 'Accept-Version: v20250224' \ -d '{ "widget_url": { "widget_type": "connect_widget", "data_request": { "products": [ "account_verification" ] } } }' ``` ```json Response theme={null} { "widget_url": { "type": "connect_widget", "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5", "user_id": "u-1234" } } ``` ## 2. Embed the Connect Widget The following guides are available to help you embed the widget, depending on your needs: * [Web Widget SDK](/connect/guides/web-sdk) * [React Native SDK](/connect/guides/react-native-sdk) * [Embed in a browser](/connect/guides/widget_loader_deprecated) using the JavaScript Loader * [Embed in a Webview](/connect/guides/webviews) **BEST PRACTICES** Follow our [best practices](/connect/best-practices) to enhance the user experience and improve conversion. ## 3. Handle Widget Events To let you know what's happening inside the widget as the widget takes the user through the connection process, MX sends widget events. For example, the **Connect Loaded** event tells you when the widget loads. While you can leverage some events for data-tracking purposes, others you must handle. The way you'll handle these events depends on the method you chose to embed the widget. For a list of all events and how to handle them, see [Widget Events](/connect/widget-events). **Considerations** For a list of important widget events and what to do when you retrieve them, see [Notable Widget Events](/connect/widget-events#notable-widget-events). Your native app must intercept **all** widget events and decide to either block or allow the event and send the user to the browser (like when a user is trying to visit a bank's site or trying to authenticate via OAuth). Failure to appropriately handle navigation events in a WebView can lead to broken behavior, like replacing the Connect Widget with the bank's website with no way for the user to get back. ## 4. Build an OAuth Flow **REGISTERING FOR OAUTH** Before you can use OAuth with real institutions, you must [register for OAuth](/resources/oauth-guide/#registration) and request production access. If you haven't registered yet, you can still use our test institutions. [OAuth](/resources/oauth-guide) is a secure and standardized way to perform authentication without exchanging sensitive credentials like usernames and passwords. To connect a user to their financial institution using OAuth, you'll follow this general workflow: 1. Send the user to the financial institution's site 2. Return the user to the Connect Widget **REACT NATIVE SDK** If you're using our [React Native SDK](/connect/guides/react-native-sdk), OAuth is automatically handled. Follow our [separate guide](/resources/oauth-guide/oauth-in-connect-widget) to connect users to institutions that require OAuth. You can use the MXCU test institution to test a more realistic OAuth flow. See [Testing OAuth with MXCU](/resources/test-platform/mxcu/testing-oauth-with-mxcu). ## 5. (Optional) Build a Microdeposits Flow If you're using the widget to verify account details, you can use [Microdeposits](/products/connectivity/microdeposits) so users can still verify their details with institutions that don't support [Instant Account Verification](/products/connectivity/instant-account-verification). For more info, see [Microdeposits Workflow in the Connect Widget](/products/connectivity/microdeposits/connect-widget). ## 6. Monitor Connection Statuses When a user connects to an institution, a `member` is created in the MX system. To proactively resolve connections issues that may arise, such as MFA challenges or credential changes, you **must** monitor the `connection_status` of each `member` that belongs to a user. For guidance on how to handle each possible status, see [Member Connection Statuses](/api-reference/platform-api/reference/members#member-connection-statuses). ## 7. Ensure Data Aggregated If the `member` has a `connection_status` of `CONNECTED` and the `is_being_aggregated` field is `false`, you're ready to retrieve the data from this connection. When the widget is open, the [Member Connected](/connect/widget-events#member-connected) widget event will signal to you when the connection between the user and the financial institution has been successfully established. To handle cases where the user initiated a connection to their institution then closed the widget before it finished aggregating, you must implement a polling workflow: 1. Request the [Read Member Status](/api-reference/platform-api/reference/read-member-status) endpoint. 2. In the response, check the `connection_status` and `is_being_aggregated` fields. 3. If `connection_status` is `CONNECTED` and `is_being_aggregated` is `false`, exit this workflow and retrieve the data. If not, we recommend waiting 3 seconds before repeating this polling workflow. ## 8. Retrieve Data If the member has a `connection_status` of `CONNECTED` and the `is_being_aggregated` field is `false`, you're ready to retrieve the data from this connection. **TIP** Consider checking the `successfully_aggregated_at` field. Depending on when the member last aggregated successfully, you can choose to aggregate the `member` again. The following table shows you how to retrieve the data you set in your widget URL request. For your convenience, some data may have multiple endpoints for its retrieval. | Requested Data | How to Retrieve It | | :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `accounts` or `transactions` | [List Accounts](/api-reference/platform-api/reference/list-user-accounts), [List Member Accounts](/api-reference/platform-api/reference/list-member-accounts), [Read Account](/api-reference/platform-api/reference/read-account), [Read Account by Member](/api-reference/platform-api/reference/read-account-by-member), [List Transactions by Account](/api-reference/platform-api/reference/list-transactions-by-account), [List Transactions](/api-reference/platform-api/reference/list-transactions), or [Read Transaction](/api-reference/platform-api/reference/read-transaction) | | `identification` | [List Account Owners by Member](/api-reference/platform-api/reference/list-account-owners-by-member) | | `verification` | [List Account Numbers by Member](/api-reference/platform-api/reference/list-account-numbers-by-member) or [List Account Numbers by Account](/api-reference/platform-api/reference/list-account-numbers-by-account) | | `statements` | 1. [List Statements by Member](/api-reference/platform-api/reference/list-statements-by-member) or [Read Statement by Member](/api-reference/platform-api/reference/read-statement-by-member)
2. (Optional) [Download Statement PDF](/api-reference/platform-api/reference/download-statement-pdf) | | `transaction_history` | 1. [List Member Accounts](/api-reference/platform-api/reference/list-member-accounts), [Read Account](/api-reference/platform-api/reference/read-account), or another `GET` accounts endpoint and save the resulting `guid`
2. Use the `guid` from the previous response in [List Transactions by Account](/api-reference/platform-api/reference/list-transactions-by-account) | | `investments` | [List Holdings by Member](/api-reference/platform-api/reference/list-holdings-by-member), [List Holdings by User](/api-reference/platform-api/reference/list-holdings-by-user), [List Holdings by Account](/api-reference/platform-api/reference/list-holdings-by-account), or [Read Holding](/api-reference/platform-api/reference/read-holding) | | `rewards` | [List Rewards](/api-reference/platform-api/reference/list-rewards) or [Read Reward](/api-reference/platform-api/reference/read-reward) | **SUCCESS** You've embedded our widget and can now retrieve data from a user's connection to their financial institution!