> ## 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. # Request widget URL > 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). ## OpenAPI ````yaml openapi/platform-api/v20111101.yaml POST /users/{user_guid}/widget_urls openapi: 3.0.0 info: contact: name: MX Platform API url: https://www.mx.com/products/platform-api description: > The MX Platform API is a powerful, fully-featured API designed to make aggregating and enhancing financial data easy and reliable. It can seamlessly connect your app or website to tens of thousands of financial institutions. title: MX Platform API version: '20111101' servers: - url: https://int-api.mx.com - url: https://api.mx.com security: - basicAuth: [] tags: - name: authorization - name: widgets - name: users - name: members - name: institutions - name: accounts - name: transactions - name: microdeposits - name: managed data - name: transaction rules - name: statements - name: merchants - name: categories - name: insights - name: investment holdings - name: spending plan - name: goals - name: budgets - name: monthly cash flow profile - name: notifications - name: taggings - name: tags - name: deprecated - name: processor token - name: verifiable credentials - name: rewards - name: ach return paths: /users/{user_guid}/widget_urls: post: tags: - widgets summary: Request widget URL description: > 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). operationId: requestWidgetURL parameters: - $ref: '#/components/parameters/acceptLanguage' - $ref: '#/components/parameters/xCallback' - $ref: '#/components/parameters/userGuid' requestBody: content: application/json: schema: $ref: '#/components/schemas/WidgetRequestBody' description: The widget url configuration options. required: true responses: '200': content: application/vnd.mx.api.v1+json: schema: $ref: '#/components/schemas/WidgetResponseBody' description: OK components: parameters: acceptLanguage: description: The desired language of the widget. example: en-US in: header name: Accept-Language schema: type: string xCallback: description: >- The base64 encoded string defined in this header will be returned in the [Member](/resources/webhooks/member/) and [Member Data Updated](/resources/webhooks/member#member-data-updated) webhooks. This allows you to trace user interactions and workflows initiated externally and internally in the MX Platform. Max 1024 characters. example: 813e50bd-4a7e-4517-b6bb-9eef65a68cbd in: header name: X-CALLBACK-PAYLOAD schema: type: string userGuid: description: The unique identifier for a `user`, beginning with the prefix `USR-`. example: USR-fa7537f3-48aa-a683-a02a-b18940482f54 in: path name: user_guid required: true schema: type: string schemas: WidgetRequestBody: properties: widget_url: $ref: '#/components/schemas/WidgetRequest' type: object WidgetResponseBody: properties: widget_url: $ref: '#/components/schemas/WidgetResponse' type: object WidgetRequest: properties: client_redirect_url: example: https://{yoursite.com} type: string description: > 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: example: light type: string description: >- 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: example: false type: boolean description: >- 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: example: mxbank type: string description: > 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: example: INS-f1a3285d-e855-b61f-6aa7-8ae575c0e0e9 type: string description: > 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: example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b type: string description: > 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: example: false type: boolean description: > 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: example: false type: boolean description: > 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: example: false type: boolean description: > 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: example: false type: boolean description: > Only use this option if the `widget_type` is set to `connect_widget`. 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: - The widget will only search for and display institutions that support the data the `mode` (`aggregation` or `verification`) is aggregating and AOI. - The member connected postMessage event will not be sent until both aggregations are complete. include_transactions: example: true type: boolean description: > 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: example: null type: string nullable: true description: > 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: example: - US - CA type: array items: type: string description: > 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: example: false type: boolean description: > 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: example: null type: string nullable: true description: > 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: example: aggregation type: string description: > 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: example: BROWSER type: string description: > 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: example: 4 type: integer description: > 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: type: string description: > 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: example: false type: boolean description: > 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: type: array description: >- 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`. items: type: string enum: - MONEY_MOVEMENT - PFM example: - PFM widget_type: example: connect_widget type: string description: > 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. required: - widget_type type: object WidgetResponse: properties: type: example: connect_widget nullable: true type: string url: example: >- https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5 nullable: true type: string user_id: example: U-jeff-201709221210 nullable: true type: string type: object securitySchemes: basicAuth: scheme: basic type: http ````