openapi: 3.2.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 Widgets API version: '20250224' servers: - url: https://int-api.mx.com - url: https://api.mx.com security: - basicAuth: [] tags: - 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}/members/{member_identifier}/oauth_window_uri: get: description: This endpoint will generate an `oauth_window_uri` for the specified `member`. operationId: requestOAuthWindowURI parameters: - $ref: '#/components/parameters/acceptVersion' - $ref: '#/components/parameters/clientRedirectUrl' - $ref: '#/components/parameters/enableApp2app' - $ref: '#/components/parameters/memberIdentifier' - $ref: '#/components/parameters/referralSource' - $ref: '#/components/parameters/skipAggregation' - $ref: '#/components/parameters/uiMessageWebviewUrlScheme' - $ref: '#/components/parameters/userIdentifier' responses: '200': content: application/json: schema: $ref: '#/components/schemas/OAuthWindowResponseBody' description: OK summary: Request oauth window uri tags: - widgets /users/{user_identifier}/widget_urls: post: 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 summary: Request widget URL tags: - widgets components: parameters: memberIdentifier: description: Use either the member `id` you defined or the MX-defined member `guid`. See [MX-Defined GUIDs vs IDs Defined by You](/products/connectivity/overview/held-data/#mx-defined-guids-vs-ids-defined-by-you). name: member_identifier in: path required: true schema: type: string enableApp2app: description: This indicates whether OAuth app2app behavior is enabled for institutions that support it. Defaults to `true`. When set to `false`, any `oauth_window_uri` generated will **not** direct the end user to the institution's mobile application. This setting is not persistent. This setting currently only affects Chase institutions. example: 'false' in: query name: enable_app2app schema: type: string referralSource: description: Must be either `BROWSER` or `APP` depending on the implementation. Defaults to `BROWSER`. example: APP in: query name: referral_source schema: type: string acceptVersion: name: Accept-Version in: header required: true schema: type: string default: v20250224 example: v20250224 description: MX Platform API version. 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 acceptLanguage: description: The desired language of the widget. example: en-US in: header name: Accept-Language schema: type: string skipAggregation: description: Setting this parameter to `true` will prevent the member from automatically aggregating after being redirected from the authorization page. example: false in: query name: skip_aggregation schema: type: boolean 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 clientRedirectUrl: description: A URL that MX will redirect to at the end of OAuth with additional query parameters. Only available with `referral_source=APP`. example: https://{yoursite.com} in: query name: client_redirect_url schema: type: string uiMessageWebviewUrlScheme: description: A scheme for routing the user back to the application state they were previously in. Only available with `referral_source=APP`. in: query name: ui_message_webview_url_scheme schema: type: string schemas: 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 type: - string - 'null' 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 type: - string - 'null' user_id: description: The unique partner-defined identifier for the user. example: u-1234 type: - string - 'null' type: object 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 type: - string - 'null' 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 type: - string - 'null' 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 type: - string - 'null' 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 type: - boolean - 'null' 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 - 'null' 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 - 'null' 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. \n\nIf you're requesting the Connect or Connections Widgets, you must use the Accept-Language header.\n" 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 SupportedProducts: type: string enum: - account_verification - identity_verification - transactions - transaction_history - statements - investments - rewards OAuthWindowResponseBody: properties: member: $ref: '#/components/schemas/OAuthWindowResponse' type: object 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 OAuthWindowResponse: properties: guid: description: The unique identifier for the member. Defined by MX. example: MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f type: - string - 'null' oauth_window_uri: description: When connecting a member using OAuth, this field will contain the URL to send the user to in order to authenticate, otherwise it will be blank. example: https://mxbank.mx.com/oauth/authorize?client_id=b8OikQ4Ep3NuSUrQ13DdvFuwpNx-qqoAsJDVAQCyLkQ&redirect_uri=https%3A%2F%2Fint-app.moneydesktop.com%2Foauth%2Fredirect_from&response_type=code&scope=openid&state=d745bd4ee6f0f9c184757f574bcc2df2 type: - string - 'null' type: object WidgetResponseBody: properties: widget_url: $ref: '#/components/schemas/WidgetResponse' type: object 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`. 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 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}'' ``` ' bearerAuth: type: http scheme: bearer