> ## 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/v20250224.yaml POST /users/{user_identifier}/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. ## What's Changed? Several endpoints, headers, and fields changed in `v20250224`. For more on breaking changes, refer to our [versioning](/api-reference/platform-api/overview/versioning#v20250224) and [migration](/api-reference/platform-api/overview/migration) guides. ## Version Header Versions are set in the `Accept-Version` header of API requests. Version numbers correspond with the date associated with that version. The example below uses the version `v20250224`. ``` -H 'Accept: application/json' -H 'Accept-Version: v20250224' ``` --- title: MX Platform API version: '20250224' servers: - url: https://int-api.mx.com - url: https://api.mx.com security: - basicAuth: [] tags: - name: authorization - name: accounts description: > The Accounts endpoints represent a user's checking, savings, mortgage, 401(k), or other types of accounts held by a financial institution. An account belongs to a `member`, which represents the user's overall relationship with a particular financial institution. A checking account may be just one part of a larger relationship that could also include a car loan and a savings account. Accounts—and the transactions associated with them—are updated every 24 hours, unless the associated `user` is disabled. You can also create manual accounts. Since a manual account has no credentials tied to the member, the account will never aggregate or include data from a data feed. All manual accounts are automatically created under the Manual Institution member. - name: ach return description: > The features documented here are in a beta state, and this documentation is considered draft material subject to frequent change. Using our Platform API, you can securely submit ACH Returns to reduce your ACH return rates and automate your ACH return process. You can query the status and outcomes of your submitted ACH returns to track progress and access resolution details. - name: budgets description: > Use these endpoints to create and manage budgets for your end users. You can create a budget for a specific category or autogenerate a budget for several categories based on existing transactions. Each budget has a `category_guid`, relating to one of the [categories](docs.mx.com/api-reference/platform-api/reference/categories#default-categories-and-subcategories). - name: categories description: > A `transaction` can have its `category` set to one of MX’s default categories or a custom category for a specific `user`. See [Default Categories and Subcategories](docs.mx.com/api-reference/platform-api/reference/categories#default-categories-and-subcategories) for a complete list. - name: deprecated - name: goals description: > Use these endpoints to create and manage goals for a `user`. You can also reposition goals to adjust their priority levels. Every goal has a track type and a meta type. The [track type](docs.mx.com/api-reference/platform-api/reference/goals/#goal-track-type) is the overall classification of the goal (debt, savings, retirement, or emergency fund) while the [meta type](docs.mx.com/api-reference/platform-api/reference/goals/#goal-meta-type) is the specific classification (like college, house, vacation, and so on). - name: insights description: > Use these endpoints to build customizable user experiences in UIs powered by our Financial Insights data. With Financial Insights, your users will receive personalized insights based on their transaction history. Want to learn more about the product? See [Financial Insights](docs.mx.com/products/experience/insights). Looking for a guide to use these endpoints? See [Build Your Own Insights UI](docs.mx.com/products/experience/insights/integration-guides/insights-api-guide). - name: institutions description: > Institutions represent a financial institution. A single real-world financial institution may have several `institution` objects on the MX platform. For example, the mortgage division of a financial institution might use a separate system than its everyday banking division, which is different from its credit card division. For more info, see [Institutions Overview](docs.mx.com/api-reference/reference/institutions). - name: investment holdings description: > Investment Data Enhancement lets you connect to an end user's financial institution and retrieve cleansed and enhanced investment data. By combining investment data with retail banking information, you get comprehensive insights into customer financial behaviors, risk tolerance, and investment strategies. You can [read a user's holding](docs.mx.com/api-reference/platform-api/reference/read-holding), [list all their holdings](docs.mx.com/api-reference/platform-api/reference/list-holdings), or list their holdings by [account](docs.mx.com/api-reference/platform-api/reference/list-holdings-by-account) or [member](docs.mx.com/api-reference/platform-api/reference/list-holdings-by-member). You can also [deactivate a user](docs.mx.com/api-reference/platform-api/reference/deactivate-user) from the Investment Data Enhancement. This is non-billable. - name: managed data - name: members description: > Members represent the connection between an end user and a financial institution. This institution may represent your institution or another one from which MX is aggregating data. For more info, see [Members Overview](docs.mx.com/api-reference/reference/members). - name: merchants description: > Merchants are representations of a transaction’s origin. For example, if you buy a coffee at Starbucks, the transaction merchant will be `Starbucks`. Use the `merchant_guid` and a `merchant_location_guidon` any `transaction` object to access Merchant endpoints for details like the merchant’s name, logo URL, website, street address, and more. - name: microdeposits description: > Microdeposits is an additional verification method that allows you to verify account details and navigate the process of using microdeposits and the automated clearing house (ACH) system. Make two, small ACH deposits into a consumer's account using the provided account and routing number. You can then require that the end user confirm the exact amount of each deposit to verify that they own the account and meet NACHA’s account verification. For more info, including process flows, setting block lists, and more, see [Microdeposits](docs.mx.com/products/connectivity/microdeposits). - name: monthly cash flow profile - name: notifications description: > You can only use notifications endpoints if you’re using the MX mobile application. All notifications created through the API will be of notification type `API_NOTIFICATION`, channel `PUSH`, and will not be associated to an entity. No other channels are supported. The read and list endpoints can return any notification associated with the `user`, including notifications created by MX for other channels besides `PUSH`. - name: processor token - name: rewards - name: spending plan description: > Use the Spending Plan endpoints to create your own version of our [Spending Plan Widget](docs.mx.com/products/experience/pfm/legacy-widget-overviews/spending-plan), which helps end users track their spending throughout the month. To understand key terms and how to best use these endpoints, see [Build Your Own Spending Plan UI](docs.mx.com/products/experience/pfm/integration-guides/build-your-own-spending-plan-ui). - name: statements description: > With Statements, you can retrieve a user's monthly account statements in PDF format. This data can be used for solutions like personal financial management or risk analysis. - name: taggings description: > Tags and taggings are two resources in the MX Platform API that, when used together, give end users more control over organizing their transactions. A tag is a custom label that can be applied to a transaction. After you create a tag, use it for tagging. This means you should actually apply the tag to a particular transaction. Together, they're a powerful tool for personalization, customization, and money management. For a guide on creating a tag and then applying it to a specific transaction with a tagging, see [Custom Tags and Taggings](docs.mx.com/products/experience/pfm/integration-guides/personalization/). - name: tags description: > Tags and taggings are two resources in the MX Platform API that, when used together, give end users more control over organizing their transactions. A tag is a custom label that can be applied to a transaction. After you create a tag, use it for tagging. This means you should actually apply the tag to a particular transaction. Together, they're a powerful tool for personalization, customization, and money management. For a guide on creating a tag and then applying it to a specific transaction with a tagging, see [Custom Tags and Taggings](docs.mx.com/products/experience/pfm/integration-guides/personalization/). - name: transaction rules description: > Transaction Rules allow users to automatically recategorize or rename all similar transactions according to their preferences. This only applies to future transactions. When recategorizing or renaming a transaction, the user will be asked whether they want the new data to apply to the selected transaction or to all future transactions. If they choose to apply it to all future transactions, it will create a transaction rule which will automatically apply the changes going forward. - name: transactions description: > Transactions represent any instance in which money moves into or out of an account. This could be a purchase at a business, a payroll deposit, a transfer from one account to another, an ATM withdrawal, and so on. Transactions are created automatically when a member is successfully aggregated. Each `transaction` belongs to only one `account`. For more info, see [Transactions Overview](docs.mx.com/api-reference/reference/transactions). - name: users description: > Users represent an end user using the Platform API through your web or mobile app. Users are created by MX clients and belong to a specific [client](docs.mx.com/products/connectivity/overview/data-architecture/#clients) on the platform. - name: verifiable credentials description: > MX provides Verifiable Credential endpoints that comply with web5 standards. For more info, see [Verifiable Credentials Overview](docs.mx.com/api-reference/reference/verifiable-credentials). - name: widgets description: > Use the [Request Widget URL](docs.mx.com/api-reference/platform-api/reference/request-widget-url) endpoint to generate a URL that loads one of our widgets. Many request body parameters only work for some widgets. For more info, including widget types, see [Widgets Overview](docs.mx.com/api-reference/reference/widgets). paths: /users/{user_identifier}/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/acceptVersion' - $ref: '#/components/parameters/acceptLanguage' - $ref: '#/components/parameters/xCallback' - $ref: '#/components/parameters/userIdentifier' requestBody: content: application/json: schema: type: object properties: widget_url: $ref: '#/components/schemas/WidgetRequest' description: The widget_url configuration options. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/WidgetResponseBody' description: OK components: parameters: acceptVersion: name: Accept-Version in: header required: true schema: type: string default: v20250224 example: v20250224 description: MX Platform API version. 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 userIdentifier: description: >- Use either the user `id` you defined or the MX-defined user `guid`. See [MX-Defined GUIDs vs IDs Defined by You​](/products/connectivity/overview/held-data/#mx-defined-guids-vs-ids-defined-by-you). in: path required: true name: user_identifier schema: type: string schemas: WidgetRequest: properties: client_redirect_url: 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'`. example: https://{yoursite.com} type: string color_scheme: 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`, `dark`, and `browser` (respects user's browser setting). Defaults to `light`. example: light nullable: true type: string enum: - light - browser - dark current_institution_code: 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. example: mx_bank nullable: true type: string current_institution_guid: 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. example: INS-f1a3285d-e855-b61f-6aa7-8ae575c0e0e9 type: string current_member_guid: 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. This option takes precedence over `current_institution_code` and `current_institution_guid`. example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b nullable: true type: string current_microdeposit_guid: example: MIC-1234567890 description: >- Only use this option if the `widget_type` is set to `connect_widget`. This loads the Connect Widget to whichever step the microdeposit process is currently in, which may be the verify amounts step, an error state, and so on. This field is required if attempting to load a specific microdeposit for end users to enter amounts. type: string data_request: $ref: '#/components/schemas/DataRequest' deep_link_params: $ref: '#/components/schemas/DeepLinkParams' type: object disable_background_agg: 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. example: false type: boolean disable_institution_search: description: > Only use this option if the `widget_type` is set to `connect_widget`. When set to `true`, the institution search feature in the Connect Widget will be disabled and end users will not be able to navigate to it. Defaults to `false`. This option must be used with `current_institution_code`, `current_institution_guid`, or `current_member_guid`. example: false nullable: true type: boolean 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: > Use `data_request.products` instead to set your products. 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: description: > Use `data_request.products` instead to set your products. 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. example: true type: boolean 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 every `widget_type`. 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. locale: description: > Sets the language of the widget. If you're requesting the Connect or Connections Widgets, you must use the Accept-Language header. example: fr-CA type: string mode: example: aggregation type: string description: > Use `data_request.products` instead to set your products. 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`. style: $ref: '#/components/schemas/Style' 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 and have opted in to using this field. 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/widgets) for a list of potential values. Additional request parameters may only apply to some widget types. required: - widget_type type: object WidgetResponseBody: properties: widget_url: $ref: '#/components/schemas/WidgetResponse' type: object DataRequest: type: object description: >- Contains a products array that specifies the products you want to aggregate. required: - products properties: products: description: >- Contains the products you want to aggregate upon a successful connection. For accepted products, see [Defining Products](/products/connectivity/overview/intro-to-unified-product-ordering/#defining-products). items: $ref: '#/components/schemas/SupportedProducts' type: array DeepLinkParams: description: Enables widget-specific behavior. properties: account_guid: example: ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1 type: string description: >- Only use this option if the `widget_type` is set to `spending_widget`. When used with the Legacy Spending Widget, used to filter by account. Contains an `account_guid` (string) optional param. date_range: type: object description: >- Only use this option if the `widget_type` is set to `spending_widget`. When used with the Legacy Spending widget, used to filter by date range. Set the `date_range` using `start_date` (string) and `end_date` (string). properties: start_date: type: string description: The start date of the range in `YYYY-MM-DD` format. example: '2023-01-01' end_date: type: string description: The end date of the range in `YYYY-MM-DD` format. example: '2023-12-31' launch_integration: example: direct-deposit type: string description: >- Only use this option if the `widget_type` is set to `actionable_integration_widget`. Launches a deep link integration. Valid value is `direct-deposit`. view: example: manage_income type: string description: >- When used with the Cash Flow, Settings, or Money Dashboard widget, sets the widget's default view. Valid value for Cash Flow or Money Dashboard Widgets is `manage_income.` Valid values for the Notifications section of the Settings Widget (`notifications_settings_widget`) are `accounts`, `budgets`, or `insights`. widget: example: budgets type: string description: >- Only use this option if the `widget_type` is set to `master_widget`. Launches a specific view in the Master Widget. Valid values are `accounts`, `budgets`, `cash_flow`, `debts`, `finstrong`, `goals`, `insights`, `investments`, `networth`, `recurringtransactions`, `spending`, `transactions`, and `trends`. Style: type: object description: Contains fields to customize the appearance of a widget. required: - font_name properties: font_name: type: string description: Sets the widget's font. Pass any Google font to change it. example: Roboto WidgetResponse: properties: type: description: > This determines which widget URL you'll receive. Additional request parameters may only apply to some widget types. example: connect_widget nullable: true type: string enum: - accounts_widget - mini_accounts_widget - actionable_integration_widget - budgets_widget - mini_budgets_widget - cash_flow_widget - mini_cash_flow_widget - connect_widget - connections_widget - debts_widget - finstrong_widget - mini_finstrong_widget - goals_widget - help_widget - master_widget - money_dashboard_widget - net_worth_widget - mini_net_worth_widget - notifications_settings_widget - recurringtransactions_widget - mini_recurringtransactions_widget - settings_widget - spending_widget - mini_spending_widget - spending_plan_widget - mini_spending_plan_widget - transaction_rules_widget - transactions_widget - trends_widget - mini_trends_widget url: description: The URL for accessing the widget. example: >- https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5 nullable: true type: string user_id: description: The unique partner-defined identifier for the user. example: u-1234 nullable: true type: string type: object SupportedProducts: type: string enum: - account_verification - identity_verification - transactions - transaction_history - statements - investments - rewards securitySchemes: basicAuth: scheme: basic type: http description: > The MX Platform API requires basic access authentication using your `client_id` and `api_key`. These credentials must be Base64 encoded and included in the Authorization header of each API request to ensure secure access. Here's an example using curl to access `v20250224`. Replace `https://int-api.mx.com/endpoint` with the actual API endpoint you wish to access and your Base64 encoded `client_id` and `api_key`. ``` curl -L -X POST `https://int-api.mx.com/endpoint' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Accept-Version: v20250224' -H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' ``` ````