---
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`.
    - `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` unknown[] — An array of strings that filters institutions in the widget by the specified country code. Acceptable codes include `US`, `CA`, and `MX` (Mexico).
      - unknown
    - `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

## Changes

> 46 revisions in range; 1 not diffed.

- **2025-11-05** `e74cd2b059b5` — 9 info
  - api tag `widgets` added
  - api tag `mx_platform` removed
  - added the new optional `header` request parameter `X-CALLBACK-PAYLOAD`
  - added the new optional request property `widget_url/connections_use_case_filter`
  - …5 more
- **2024-05-07** `bcb952b55c19` — 1 info
  - added the new optional request property `widget_url/microwidget_instance_id`
- **2024-02-28** `1d7939fa1177` — 1 info
  - added the new optional request property `widget_url/insight_guid`
- **2024-02-13** `a13220639504` — 1 warning, 1 info
  - removed the request property `widget_url/insight_guid`
  - added the new optional request property `widget_url/microwidget_instance_id`
- **2024-02-13** `8f0bc3813b96` — 1 info
  - added the new optional request property `widget_url/insight_guid`

[Change history](https://skmtc.dev/mx/apis/mx-platform-api/changes/users/:user_guid/widget_urls/post.md)

---

[API](https://skmtc.dev/mx/apis/mx-platform-api.md) · [All operations](https://skmtc.dev/mx/apis/mx-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mx/mx-platform-api/revisions/e74cd2b059b5/schema)