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. Just getting started? See our [use case guides](/use-cases/). ' title: MX Platform accounts widgets API version: '20111101' servers: - url: https://int-api.mx.com - url: https://api.mx.com security: - basicAuth: [] tags: - name: widgets paths: /users/{user_guid}/connect_widget_url: post: description: This endpoint will return a URL for an embeddable version of MX Connect. operationId: requestConnectWidgetURL parameters: - $ref: '#/components/parameters/userGuid' requestBody: content: application/json: schema: $ref: '#/components/schemas/ConnectWidgetRequestBody' description: Optional config options for WebView (is_mobile_webview, current_institution_code, current_member_guid, update_credentials) required: true responses: '200': content: application/vnd.mx.api.v1+json: schema: $ref: '#/components/schemas/ConnectWidgetResponseBody' description: OK summary: (Deprecated) Request connect widget URL deprecated: true tags: - widgets /users/{user_guid}/members/{member_guid}/oauth_window_uri: get: description: This endpoint will generate an `oauth_window_uri` for the specified `member`. operationId: requestOAuthWindowURI parameters: - $ref: '#/components/parameters/clientRedirectUrl' - $ref: '#/components/parameters/enableApp2app' - $ref: '#/components/parameters/memberGuid' - $ref: '#/components/parameters/referralSource' - $ref: '#/components/parameters/skipAggregation' - $ref: '#/components/parameters/uiMessageWebviewUrlScheme' - $ref: '#/components/parameters/userGuid' responses: '200': content: application/vnd.mx.api.v1+json: schema: $ref: '#/components/schemas/OAuthWindowResponseBody' description: OK summary: Request oauth window uri tags: - widgets /users/{user_guid}/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/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 summary: Request widget URL tags: - widgets /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 components: schemas: 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 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: 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 ConnectWidgetRequestBody: properties: config: $ref: '#/components/schemas/ConnectWidgetRequest' type: object OAuthWindowResponse: properties: guid: example: MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f nullable: true type: string oauth_window_uri: 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 nullable: true type: string type: object WidgetResponseBody: properties: widget_url: $ref: '#/components/schemas/WidgetResponse' type: object ConnectWidgetRequest: properties: client_redirect_url: example: https://{yoursite.com} type: string color_scheme: example: light type: string current_institution_code: example: mxbank type: string current_member_guid: example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b type: string disable_background_agg: example: false type: boolean disable_institution_search: example: false type: boolean enable_app2app: example: false type: boolean description: '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 include_transactions: example: true type: boolean is_mobile_webview: example: false type: boolean mode: example: aggregation type: string oauth_referral_source: example: BROWSER type: string ui_message_version: example: 4 type: integer ui_message_webview_url_scheme: type: string update_credentials: example: false type: boolean type: object ConnectWidgetResponse: properties: connect_widget_url: example: https://int-widgets.moneydesktop.com/md/connect/jb1rA14m85tw2lyvpgfx4gc6d3Z8z8Ayb8 nullable: true type: string guid: example: USR-fa7537f3-48aa-a683-a02a-b18940482f54 nullable: true type: string type: object WidgetRequestBody: properties: widget_url: $ref: '#/components/schemas/WidgetRequest' type: object ConnectWidgetResponseBody: properties: user: $ref: '#/components/schemas/ConnectWidgetResponse' type: object OAuthWindowResponseBody: properties: member: $ref: '#/components/schemas/OAuthWindowResponse' 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 parameters: 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 acceptVersion: name: Accept-Version in: header required: true schema: type: string default: v20250224 example: v20250224 description: MX Platform API version. 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 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 userIdentifier: description: Use either the user `id` you defined or the MX-defined user `guid`. See [MX-Defined GUIDs vs IDs Defined by You​](https://docs.mx.com/products/connectivity/overview/held-data/#mx-defined-guids-vs-ids-defined-by-you). in: path required: true name: user_identifier 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 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 memberGuid: description: The unique id for a `member`. example: MBR-7c6f361b-e582-15b6-60c0-358f12466b4b in: path name: member_guid required: true 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 acceptLanguage: description: The desired language of the widget. example: en-US in: header name: Accept-Language 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 memberIdentifier: description: Use either the member `id` you defined or the MX-defined member `guid`. See [MX-Defined GUIDs vs IDs Defined by You](https://docs.mx.com/products/connectivity/overview/held-data/#mx-defined-guids-vs-ids-defined-by-you). name: member_identifier in: path required: true schema: type: string securitySchemes: bearerAuth: type: http scheme: bearer basicAuth: scheme: basic type: http