--- title: "Request widget URL" method: POST path: "/users/{user_guid}/widget_urls" tags: ["widgets"] --- # Request widget URL `POST /users/{user_guid}/widget_urls` Get an embeddable URL for integrating a widget into your website or app. 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. Include the `widget_type` in the request body to specify which widget you want to embed—the Connect Widget, a Personal Financial Management widget, or an Insights widget. Some request parameters are specific to certain widget types. To embed the Connect Widget, set `widget_type` to `connect_widget`. For a full list of available widget types, see [Widget Types](/api-reference/platform-api/reference/widgets#widget-types). ## Path parameters - `user_guid` string, required ## Headers - `Accept-Language` string - `X-CALLBACK-PAYLOAD` string ## Request body - WidgetRequestBody - `widget_url` WidgetRequest - `client_redirect_url` string — Only use this option if the `widget_type` is set to `connect_widget`. This determines the redirect destination at the end of OAuth when used with `is_mobile_webview: true` or `oauth_referral_source: 'APP'`. - `color_scheme` string — This option can be passed to any `widget_type` but will not affect [legacy PFM widgets](products/experience/pfm/legacy-widget-overviews/). Load the widget with the specified `color_scheme`; options are `light`, `browser` (respects user's browser setting), and `dark`. Defaults to `light`. - `connections_use_case_filter` boolean — To use this parameter, you must also set `use_cases` in the same request. If `connections_use_case_filter` is set to `true`, the Connections Widget will only show connections (members) with the `use_cases` you set in the same request. For some examples, see [Filter Connections](/products/experience/pfm/widget-overviews/connections-widget#example-1). - `current_institution_code` string — Only use this option if the `widget_type` is set to `connect_widget`. Load the widget into the credential view for the specified institution. - `current_institution_guid` string — Only use this option if the `widget_type` is set to `connect_widget`. Load the widget into the credential view for the specified institution. - `current_member_guid` string — Only use this option if the `widget_type` is set to `connect_widget`. 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`. - `disable_background_agg` boolean — Only use this option if the `widget_type` is set to `connect_widget`. 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. - `disable_institution_search` boolean — Only use this option if the `widget_type` is set to `connect_widget`. This determines whether the institution search is displayed within the Connect Widget. This option must be used with `current_institution_code`, `current_instituion_guid`, or `current_member_guid`. When set to `true`, the institution search feature will be disabled and end users will not be able to navigate to it. Defaults to `false`. If you set `disable_institution_search` to `true`, you must also listen for the [backToSearch event](/connect/guides/handling-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. 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. This may trigger during several steps in the Connect Widget flow, such as Connected, MDV/Microdeposits Verified, Login Error, and Credentials/OAuth (back button). - `enable_app2app` boolean — Only use this option if the `widget_type` is set to `connect_widget`. 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. - `include_identity` boolean — Only use this option if the `widget_type` is set to `connect_widget`. This determines whether an account owner identification (AOI, previously called identity verification) is run in addition to the process specified by the `mode`. Defaults to `false`. This can be set in either `aggregation` or `verification` mode. The AOI runs after the primary process is complete. - `include_transactions` boolean — Only use this option if the `widget_type` is set to `connect_widget`. This determines whether transaction data are retrieved. Defaults to `true` in aggregation mode and `false` in verification mode. This can be set in either `aggregation` or `verification` mode. This option does not affect future foreground or background aggregations. - `insight_guid` string, nullable — Only use this option if the `widget_type` is set to `pulse_widget`. Set this to the insight guid you want to appear at the top of the insights feed. - `iso_country_code` string[] — An array of strings that filters institutions in the widget by the specified country code. Acceptable codes include `US`, `CA`, and `MX` (Mexico). - `is_mobile_webview` boolean — This option is for all `widget_type`s. This configures the widget to render in a mobile WebView. JavaScript event postMessages are replaced with URL updates. - `microwidget_instance_id` string, nullable — Only use this option if the `widget_type` is set to `micro_pulse_carousel_widget`. Set this to a unique value for each instance of the Micro Widget. This lets us collect unique data for each instance of the widget. - `mode` string — Only use this option if the `widget_type` is set to `connect_widget`. `mode` is the most important option for the Connect Widget. This determines what kind of process Connect will run, which affects how you should set many other options. Defaults to `aggregation`. `aggregation` mode retrieves account and transaction data; in other words, this runs a standard aggregation. `verification` mode retrieves account numbers and routing/transit numbers; in other words, it runs an Instant Account Verification (IAV). By default, verification mode does not retrieve transaction data; this default can be modified with secondary options. By default, background aggregation is disabled for all members created in verification mode; this default can be modified with secondary options. - `oauth_referral_source` string — Only use this option if the `widget_type` is set to `connect_widget`. 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`. - `ui_message_version` integer — This option is for all `widget_type`s. This determines which version of postMessage events are triggered. Defaults to 4. All new implementations must use version 4. Prior versions are deprecated. - `ui_message_webview_url_scheme` string — Only use this option if the `widget_type` is set to `connect_widget`. 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`. - `update_credentials` boolean — Only use this option if the `widget_type` is set to `connect_widget`. Load the widget into a view that allows them to update the current member. Optionally used with `current_member_guid`. This option should be used sparingly. The best practice is to use `current_member_guid` and let the widget resolve the issue. - `use_cases` string[] — The use case that will be associated with any members created through the widget. Valid values are `PFM` and/or `MONEY_MOVEMENT`. This is **required** if you've met with MX, opted in to using this field, and are requesting a widget with a `widget_type` of `connect_widget` or `connections_widget`. - `widget_type` string, required — This determines which widget URL you'll receive. See [Widget Types](/api-reference/platform-api/reference/widget-types) for a list of potential values. Additional request parameters may only apply to some widget types. ## Response `200` OK --- [API](https://skmtc.net/mx/apis/mx-platform-api.md) · [All operations](https://skmtc.net/mx/apis/mx-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mx/mx-platform-api/revisions/b6632646ee89/schema)