Skip to main content
By the end of this guide, you’ll be able to connect a user to their financial institution, resolve connection errors, and retrieve financial data using the Platform API and Connect Widget.
LOOKING FOR PLATFORM V2011101 GUIDES?If you’re using Platform API v2011101, see Legacy Guides.

​
Prerequisites

Before using this guide, ensure the following:
  • You’ve signed up for the Client Dashboard and can access your API keys
  • Your IP addresses are whitelisted in the Client Dashboard
  • Users exist on the MX system or you’ve created a user
  • You have registered for OAuth, unless you’re using our test institution
  • You have set up how you’ll send held data to MX (if your institution has held data)

​
1. Get the Widget URL

To open the Connect Widget, you’ll use the Request Widget URL endpoint to retrieve a unique URL. The parameters you set in this request determine how the widget behaves.
INFOThe 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.
In this request, set widget_type to connect_widget and data_request.products to include the products you want to aggregate. Considerations
The products you set in your widget URL request (through the data_request.products) determine what data will be aggregated and which institutions appear in the widget search results.You can define the products using the following values.
NOTEBalance data is always included and doesn’t need to be set.
ProductValue
Instant Account Verificationaccount_verification
Account Owner Identificationidentity_verification
Account Aggregationtransactions
Extended Historytransaction_history
Statementsstatements
Investmentsinvestments
Rewardsrewards
INFONot every field will populate for each product, as data availability depends on what the institution provides.
Specifying multiple products restricts the widget to show only institutions that support all the requested products. This filtering affects conversion in the following ways:
  • Fewer Available Institutions: Many institutions support only one product. More products requested means fewer institutions displayed to users. For example, requesting both account_verification and identity_verification will only show institutions that are capable of providing both products.
  • OAuth Consent Requirements: For OAuth institutions, users must grant permission for all requested products. If they decline any permission, the connection will fail and they’ll need to restart the OAuth flow.
Balance your data needs against potential reduction in available institutions and connection success rates.
curl -i -X POST 'https://int-api.mx.com/users/{user_guid}/widget_urls' \
-u 'client_id:api_key' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' \
-H 'Accept-Version: v20250224' \
-d '{
      "widget_url": {
        "widget_type": "connect_widget",
        "data_request": {
          "products": [
            "account_verification"
          ]
        }
      }
    }'

{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "u-1234"
  }
}

​
2. Embed the Connect Widget

The following guides are available to help you embed the widget, depending on your needs:
BEST PRACTICESFollow our best practices to enhance the user experience and improve conversion.

​
3. Handle Widget Events

To let you know what’s happening inside the widget as the widget takes the user through the connection process, MX sends widget events. For example, the Connect Loaded event tells you when the widget loads. While you can leverage some events for data-tracking purposes, others you must handle. The way you’ll handle these events depends on the method you chose to embed the widget. For a list of all events and how to handle them, see Widget Events. Considerations
For a list of important widget events and what to do when you retrieve them, see Notable Widget Events.
Your native app must intercept all widget events and decide to either block or allow the event and send the user to the browser (like when a user is trying to visit a bank’s site or trying to authenticate via OAuth).Failure to appropriately handle navigation events in a WebView can lead to broken behavior, like replacing the Connect Widget with the bank’s website with no way for the user to get back.

​
4. Build an OAuth Flow

REGISTERING FOR OAUTHBefore you can use OAuth with real institutions, you must register for OAuth and request production access. If you haven’t registered yet, you can still use our test institutions.
OAuth is a secure and standardized way to perform authentication without exchanging sensitive credentials like usernames and passwords. To connect a user to their financial institution using OAuth, you’ll follow this general workflow:
  1. Send the user to the financial institution’s site
  2. Return the user to the Connect Widget
REACT NATIVE SDKIf you’re using our React Native SDK, OAuth is automatically handled.
Follow our separate guide to connect users to institutions that require OAuth. You can use the MXCU test institution to test a more realistic OAuth flow. See Testing OAuth with MXCU.

​
5. (Optional) Build a Microdeposits Flow

If you’re using the widget to verify account details, you can use Microdeposits so users can still verify their details with institutions that don’t support Instant Account Verification. For more info, see Microdeposits Workflow in the Connect Widget.

​
6. Monitor Connection Statuses

When a user connects to an institution, a member is created in the MX system. To proactively resolve connections issues that may arise, such as MFA challenges or credential changes, you must monitor the connection_status of each member that belongs to a user. For guidance on how to handle each possible status, see Member Connection Statuses.

​
7. Ensure Data Aggregated

If the member has a connection_status of CONNECTED and the is_being_aggregated field is false, you’re ready to retrieve the data from this connection. When the widget is open, the Member Connected widget event will signal to you when the connection between the user and the financial institution has been successfully established. To handle cases where the user initiated a connection to their institution then closed the widget before it finished aggregating, you must implement a polling workflow:
  1. Request the Read Member Status endpoint.
  2. In the response, check the connection_status and is_being_aggregated fields.
  3. If connection_status is CONNECTED and is_being_aggregated is false, exit this workflow and retrieve the data. If not, we recommend waiting 3 seconds before repeating this polling workflow.

​
8. Retrieve Data

If the member has a connection_status of CONNECTED and the is_being_aggregated field is false, you’re ready to retrieve the data from this connection.
TIPConsider checking the successfully_aggregated_at field. Depending on when the member last aggregated successfully, you can choose to aggregate the member again.
The following table shows you how to retrieve the data you set in your widget URL request. For your convenience, some data may have multiple endpoints for its retrieval.
Requested DataHow to Retrieve It
accounts or transactionsList Accounts, List Member Accounts, Read Account, Read Account by Member, List Transactions by Account, List Transactions, or Read Transaction
identificationList Account Owners by Member
verificationList Account Numbers by Member or List Account Numbers by Account
statements1. List Statements by Member or Read Statement by Member
2. (Optional) Download Statement PDF
transaction_history1. List Member Accounts, Read Account, or another GET accounts endpoint and save the resulting guid
2. Use the guid from the previous response in List Transactions by Account
investmentsList Holdings by Member, List Holdings by User, List Holdings by Account, or Read Holding
rewardsList Rewards or Read Reward
SUCCESSYou’ve embedded our widget and can now retrieve data from a user’s connection to their financial institution!