MX Technologies widgets API
The widgets API from MX Technologies — 4 operation(s) for widgets.
OpenAPI Specification
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