> ## 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. # Configure Your Connect Widget **LEGACY GUIDE** This guide is for Platform API v2011101. For guidance on the newest version, see [Connectivity Integration Guides](/products/connectivity/overview/connectivity-integration-guides/). The Connect Widget requires careful configuration for different tasks. **INFO** If you're looking for guides to implement the widget using one of our SDKs or other implementation methods, see [Implementation Guides](/connect/guides/). You'll configure your widget using the [Request Widget URL](/api-reference/platform-api/reference/request-widget-url) endpoint, which will return a URL that you'll embed into the SDK. When end users successfully connect to their institutions, the widget will automatically start aggregating data, depending on what you specified in your configuration. You'll use separate API endpoints to actually read the data the widget has aggregated. If you want to know what data the widget can aggregate, see [Data Aggregation](/connect/#data-aggregation). ## Configuration Quick Reference The following table shows the Connect Widget configurations used for common tasks. **INFO** For more guidance, see [Configure Your Connect Widget Step-by-Step](#configure-your-connect-widget-step-by-step). | Task | Configuration | | :------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Answer MFA for a specific member | Set the `current_member_guid` to a member whose `connection_status` is `CHALLENGED`. The widget will load the MFA view so the end user can respond to the MFA challenge. | | Disable search when loading a specific institution | Set `disable_institution_search` to `true` and set `current_institution_code` or `current_member_guid`. The widget will load the login view for the specified institution. You must listen to the [Back to Search](/connect/widget-events#back-to-search) event to intercept the user navigating back to search during the flow. | | Resolve a member's error(s) | Set `current_member_guid` to a member in an error state. The widget will load in the error view so the end user can resolve the error. | | Update a member's credentials | Set `current_member_guid` to the desired member's `guid`. If the member's credentials need to be updated, the widget will load the Update Credentials view for the member. | ## Configure Your Connect Widget Step-by-Step The section walks you through configuring your widget URL request. **INFO** Every step in this guide requires configuring the [Request Widget URL](/api-reference/platform-api/reference/request-widget-url) endpoint. ### 1. Set the Widget Type The `widget_type` configuration ensures the widget URL you'll receive is for the Connect Widget. ```shell focus=7:7 theme={null} curl -i -X POST https://int-api.mx.com/users/{USR-guid}/widget_urls \ -H 'Accept: application/vnd.mx.api.v1+json' \ -u 'client_id:api_key' \ -H 'Content-type: application/json' \ -d '{ "widget_url": { "widget_type": "connect_widget" } }' ``` ### 2. Set the Language Getting a widget in a specific language requires passing the desired language as a parameter in the `Accept-Language` header with requests to the [Request Widget URL](/api-reference/platform-api/reference/request-widget-url) endpoint. **Don't use the `locale` parameter in the request body;** the `Accept-Language` header is the only available option when embedding the Connect Widget by itself. If no header is provided, the Connect Widget will default to `en-US`. The following languages are supported in the Connect Widget: * `en-CA` * `en-US` * `es` * `fr` The following example sets the language of the Connect Widget that will be returned to Spanish. ```shell focus=4:4 theme={null} curl -i -X POST https://int-api.mx.com/users/{USR-guid}/widget_urls \ -H 'Accept: application/vnd.mx.api.v1+json' \ -u 'client_id:api_key' \ -H 'Accept-Language: es' \ -H 'Content-type: application/json' \ -d '{ "widget_url": { "widget_type": "connect_widget" } }' ``` ### 3. Set the Mode The `mode` configuration sets which data the widget will later aggregate, sets which events we'll detect in the widget that you could (or must) handle, and determines how you'll set some other configurations. The `mode` defaults to `aggregation` and can be set to `verification`, depending on your needs. * If you just need the widget to aggregate account and transaction data, don't set this configuration. It defaults to `aggregation`. * If you need the widget to retrieve account numbers and routing/transit numbers, relating to Instant Account Verification (IAV), then set the `mode` to `verification`. Verification mode is used to gather account and routing numbers, which we call instant account verification (IAV). Setting the `mode` to `verification` will change several behaviors for the Connect Widget and for associated members: * The end user will be prompted to verify an existing connection (if they have one) before going to search. * Connect will only search for and display institutions that support IAV. * After gathering credentials, the widget will start aggregating IAV data rather than account and transaction data. * Because this is for IAV, `include_transactions` will be set to false, so no transaction data will be gathered. If this data is needed, you must explicitly set `include_transactions` to `true`. * [Background aggregation](/products/connectivity/account-aggregation) will be disabled for members created by the Connect Widget, even if the `include_transactions` parameter is set to `true`. For existing connections, the existing background aggregation setting is preserved. * For end users who search for an institution that doesn't support IAV, the microdeposits flow begins and the end user is presented with the option to verify using microdeposits. In the microdeposit flow, no member is created on the MX platform. You must log the `microdeposit_guid` in step 5 and use it to load the widget in the correct configuration when the end user returns several days later to verify their deposit amounts. Loading with the correct `microdeposit_guid` ensures the widget prompts for verification amounts and perform other tasks related to microdeposit verifications. If you need to collect account owner identity data in addition to verification or aggregation data, you can set that in the next step. Identity data must be aggregated in addition to either Account Aggregation or Instant Account Verification data. The following example shows a request where the `mode` is set to `verification`. ```shell focus=8:8 theme={null} curl -i -X POST https://int-api.mx.com/users/{USR-guid}/widget_urls \ -H 'Accept: application/vnd.mx.api.v1+json' \ -u 'client_id:api_key' \ -H 'Content-type: application/json' \ -d '{ "widget_url": { "widget_type": "connect_widget", "mode": "verification" // defaults to "aggregation" } }' ``` ### 4. Set Other Data Configurations In addition to having the widget aggregate account and transaction data (`"mode":"aggregation"`) or account and routing numbers (`"mode":"verification"`), you can set some other configurations that also affects which data the widget will aggregate. | Option | Type | Description | | :----------------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `disable_background_agg` | Boolean | This determines whether background aggregation is enabled or disabled for the member created by the Connect Widget. Defaults to `false` in `aggregation` mode and `true` in `verification` mode. A global default for all members can be set by reaching out to MX. | | `include_identity` | Boolean | This determines whether account owner identification data (AOI, previously called "identity verification") aggregates after the data that's specified by the `mode` finishes aggregating. Defaults to `false`. This can be set in either `aggregation` or `verification` mode. Setting this to `true` will produce the following behaviors: | | `include_transactions` | Boolean | This determines whether transaction data aggregates. Defaults to `true` in aggregation mode and `false` in verification mode. This can be set in either `aggregation` or `verification` mode. This option doesn't affect future foreground or background aggregations. When `include_transactions` is set to `true` and the `mode` is set to `verification`, then a single aggregation will return the transactions and account numbers data for the verified accounts only. When `is_being_aggregated` goes to `false` then the aggregation is done. | ```shell focus=9-11 theme={null} curl -i -X POST https://int-api.mx.com/users/{USR-guid}/widget_urls \ -H 'Accept: application/vnd.mx.api.v1+json' \ -u 'client_id:api_key' \ -H 'Content-type: application/json' \ -d '{ "widget_url": { "widget_type": "connect_widget", "mode": "verification", // defaults to "aggregation". "disable_background_agg": true // defaults to `false` in `aggregation` mode and `true` in `verification` mode. "include_identity": false // defaults to false in both modes. "include_transactions": false // defaults to `true` in `aggregation` mode and `false` in `verification` mode. } }' ``` ### 5. Set Mobile Configuration If you're integrating the widget on a desktop platform, you can skip this step. If you're **integrating the widget onto a mobile platform**, you'll want to set: * `"is_mobile_webview": true` * `client_redirect_url` When `"is_mobile_webview": true` the widget will: * Send [events](/connect/widget-events) to the WebView via `window.location = {scheme}://{event path}?metadata={json encoded metadata}` instead of `window.postMessage(eventObject)`. * Set the `oauth_referral_source` to `APP` so the OAuth flow will redirect back to a native application instead of sending a postMessage to the opening window. * Prevent the widget from automatically trying to open an OAuth window; instead it will send the [OAuth requested postMessage](/connect/widget-events#oauth-requested) so your app can correctly open the OAuth window in the user agent. The following table details the configurations in this step. | Option | Type | Description | | :-------------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `client_redirect_url` | String | This determines the redirect destination at the end of OAuth when used with `is_mobile_webview: true` or `oauth_referral_source: "APP"`. For more info, see [OAuth in WebViews](/connect/guides/webviews#1-get-a-widget-url). | | `is_mobile_webview` | Boolean | This configures the widget to render in a mobile WebView. JavaScript event postMessages are replaced with URL updates. For more info, see [Events in WebViews](/connect/guides/webviews#2-handle-navigation-events). | The following example sets `is_mobile_webview` to `true`. ```shell focus=8:8 theme={null} curl -i -X POST https://int-api.mx.com/users/{USR-guid}/widget_urls \ -H 'Accept: application/vnd.mx.api.v1+json' \ -u 'client_id:api_key' \ -H 'Content-type: application/json' \ -d '{ "widget_url": { "widget_type": "connect_widget", "is_mobile_webview": true } }' ``` ### 6. Set Authentication Configurations These options are all related to authentication and how it's handled in different situations, including how some event messages are delivered. If you're **supporting OAuth flows**, you'll want to set: * `client_redirect_url` or `ui_message_webview_url_scheme` (we recommend using `client_redirect_url` if possible) * `enable_app2app` * `oauth_referral_source`. This is meant for hybrid webapp integrations. For more info, see [OAuth in WebViews](/connect/guides/webviews#alternate-redirect-option). The following table details the configurations in this step. | Option | Type | Description | | :------------------------------ | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `client_redirect_url` | String | This determines the redirect destination at the end of OAuth when used with `is_mobile_webview: true` or `oauth_referral_source: "APP"`. For more info, see [OAuth in WebViews](/connect/guides/webviews#1-get-a-widget-url). | | `enable_app2app` | Boolean | This indicates whether OAuth app2app behavior is enabled for institutions that support it. Defaults to `true`. When set to `false`, the widget will **not** direct the end user to the institution's mobile application. This setting is not persistent. This setting currently only affects Chase institutions. | | `is_mobile_webview` | Boolean | This configures the widget to render in a mobile WebView. JavaScript event postMessages are replaced with URL updates. For more info, see [Events in WebViews](/connect/guides/webviews#2-handle-navigation-events). | | `oauth_referral_source` | String | This determines how MX will respond to the result of an OAuth flow. When set to `APP`, MX will redirect to the URI specified in the `ui_message_webview_url_scheme`. When set to `BROWSER`, MX will send a postMessage but not redirect. If `is_mobile_webview` is `true`, this defaults to `APP`. If `false`, it defaults to `BROWSER`. For more info, see [OAuth in WebViews](/connect/guides/webviews#alternate-redirect-option). | | `ui_message_webview_url_scheme` | String | This is a client-defined scheme used in OAuth redirects in WebViews; also used in URL updates when these replace postMessages in WebViews. Defaults to `mx`. For more info, see [OAuth in WebViews](/connect/guides/webviews#alternate-redirect-option). | The following shows an example request for an integration on a mobile app. ```shell focus=8-11 theme={null} curl -i -X POST https://int-api.mx.com/users/{USR-guid}/widget_urls \ -H 'Accept: application/vnd.mx.api.v1+json' \ -u 'client_id:api_key' \ -H 'Content-type: application/json' \ -d '{ "widget_url": { "widget_type": "connect_widget", "is_mobile_webview": true, "enable_app2app": true, "client_redirect_url": "https://{yoursite.com}?status=success&member_guid={MBR-XXX}" } }' ``` ### 7. Set the Widget's Default View You can load the Connect Widget directly to an institution (using the institution's `code` or `guid`) or member (using the member's `guid`) to let end users complete specific tasks without manually searching for the institution. If you're using the widget in `verification` mode to prompt the end user for verification amounts and to perform other tasks related to microdeposit verifications, set the `current_microdeposit_guid` to load the widget. For more info, see [How to Request a Microdeposit Verification](/products/connectivity/microdeposits/connect-widget). **WARNING** If you set `current_institution_code`, `current_institution_guid`, or `current_member_guid` to `true`, you must set `disable_institution_search` to `true` to prevent the end user from accessing the search institution page and manually loading a different institution during the initial connection. You must also listen for the backToSearch postMessage event. See the dropdown that follows for more info. If you set `disable_institution_search` to `true`, you must also listen for the [backToSearch event](/connect/widget-events#back-to-search) to intercept the user from navigating back to search during the flow. Don't listen for any Primary Action postMessages when you disable search. **INFO** Even if you configure the Connect Widget to disable institution search, you must still listen for the postMessage. All buttons that will take a user to the search institution page are still displayed in the Connect Widget experience and your user can still select them. The postMessage will notify you that the client has taken this action so you can direct your user elsewhere. This may trigger during several "steps" in the Connect Widget flow: * Connected * MDV/Microdeposits Verified * Login Error * Credentials/OAuth (back button) The following table details the configurations in this step. | Option | Type | Description | | :--------------------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `current_institution_code` | String | Load the widget into the credential view for the specified institution. | | `current_institution_guid` | String | Load the widget into the credential view for the specified institution. | | `current_member_guid` | String | Load the widget into a specific member that contains an error or requires multifactor authentication. The widget will determine the best view to load based on the member's current state. `current_member_guid` takes precedence over `current_institution_code` and `current_institution_guid`. When you load the Connect Widget with a specific member GUID, it will determine the best course of action based on the state of that member, such as prompting for MFA or resolving an error state. Rather than trying to figure out what do with with each and every connection\_status, it is best to configure your request with the `current_member_guid` in question and allow it to automatically determine the best course of action for the end user. You should consider using this configuration with the `disable_institution_search` option to skip the search step. You will want to listen to the [backToSearch](/connect/widget-events#back-to-search) postMessages to intercept the user navigating back to search during the flow. MX **does not recommend** using this configuration with the `update_credentials` option. | | `current_microdeposit_guid` | String | Load the widget to whichever step the microdeposit process is currently in, which may be the verify amounts step, an error state, and so on. | | `disable_institution_search` | Boolean | This determines whether the institution search is displayed within the Connect Widget. This option **must** be used with `current_institution_code`, `current_institution_guid`, or `current_member_guid`. You must listen to the [backToSearch](/connect/widget-events#back-to-search) postMessages to intercept the user navigating back to search during the flow. Defaults to `false`. | | `update_credentials` | Boolean | **This option should be used sparingly** Load the widget into a view that allows them to update the current member. Optionally used with `current_member_guid`. The best practice is to use `current_member_guid` and let the widget resolve the issue. | The following example will load the Connect Widget to a specific institution. Because in this example we're loading to an institution directly, the request also disables the ability to search for institutions in the widget. ```shell focus=8-9 theme={null} curl -i -X POST https://int-api.mx.com/users/{USR-guid}/widget_urls \ -H 'Accept: application/vnd.mx.api.v1+json' \ -u 'client_id:api_key' \ -H 'Content-type: application/json' \ -d '{ "widget_url": { "widget_type": "connect_widget", "current_institution_code": "bank_code", "disable_institution_search": true // since we load the widget to an institution, we must disable search. } }' ``` ### 8. Set the Color Scheme If you want to load the widget in dark mode, set `"color_scheme": "dark"`. It defaults to `light`. ```shell focus=8:8 theme={null} curl -i -X POST https://int-api.mx.com/users/{USR-guid}/widget_urls \ -H 'Accept: application/vnd.mx.api.v1+json' \ -u 'client_id:api_key' \ -H 'Content-type: application/json' \ -d '{ "widget_url": { "widget_type": "connect_widget", "color_scheme": "dark" // defaults to "light". } }' ``` **SUCCESS** You've configured your Connect Widget!