> ## 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.
# Connect Widget Overview
The Connect Widget lets end users search for and connect to their accounts. It collects users' credentials, prompts for multifactor authentication, and resolves connection errors between end users and their financial institutions.
You'll embed the widget into your website or mobile app. We offer a React Native SDK for mobile implementations and a Web SDK for desktop implementations.
## Retrievable Data
The following are example responses for each product.
See [Account Aggregation](/products/connectivity/account-aggregation) for more info.
This sample response shows the data you can expect to get for financial accounts.
```json theme={null}
{
"accounts": [
{
"account_number": "5366",
"apr": 1.0,
"apy": 1.0,
"available_balance": 1000.0,
"available_credit": 1000.0,
"balance": 1000.0,
"cash_balance": 1000.0,
"cash_surrender_value": 1000.0,
"created_at": "2016-10-13T17:57:37.000Z",
"credit_limit": 100.0,
"currency_code": "USD",
"day_payment_is_due": 20,
"death_benefit": 1000,
"guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
"holdings_value": 1000.0,
"id": "1040434698",
"imported_at": "2015-10-13T17:57:37.000Z",
"institution_code": "chase",
"insured_name": "Frodo Baggins",
"interest_rate": 1.0,
"is_closed": false,
"is_hidden": false,
"last_payment": 100.0,
"last_payment_at": "2015-10-13T17:57:37.000Z",
"loan_amount": 1000.0,
"matures_on": "2015-10-13T17:57:37.000Z",
"member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"member_id": "member-9876",
"member_is_managed_by_user": false,
"metadata": "some metadata",
"minimum_balance": 100.0,
"minimum_payment": 10.0,
"name": "Test account 2",
"nickname": "My Checking",
"original_balance": 10.0,
"pay_out_amount": 10.0,
"payment_due_at": "2015-10-13T17:57:37.000Z",
"payoff_balance": 10.0,
"premium_amount": 1.0,
"routing_number": "68899990000000",
"started_on": "2015-10-13T17:57:37.000Z",
"subtype": "NONE",
"total_account_value": 1.0,
"type": "SAVINGS",
"updated_at": "2016-10-13T18:08:00.000Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"user_id": "partner-2345"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 1,
"total_pages": 1
}
}
```
This sample response shows the data you can expect to get for transactions.
```json theme={null}
{
"transactions": [
{
"account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
"account_id": "account123",
"amount": 61.11,
"category": "Groceries",
"category_guid": "CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8",
"check_number_string": "6812",
"created_at": "2016-10-06T09:43:42.000Z",
"currency_code": "USD",
"date": "2013-09-23T00:00:00.000Z",
"description": "Whole foods",
"extended_transaction_type": "partner_transaction_type",
"guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",
"id": "transaction-265abee9-889b-af6a-c69b-25157db2bdd9",
"is_bill_pay": false,
"is_direct_deposit": false,
"is_expense": true,
"is_fee": false,
"is_income": false,
"is_international": false,
"is_overdraft_fee": false,
"is_payroll_advance": false,
"is_recurring": false,
"is_subscription": false,
"latitude": -43.2075,
"localized_description": "This is a localized_description",
"localized_memo": "This is a localized_memo",
"longitude": 139.691706,
"member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"member_is_managed_by_user": false,
"memo": "This is a memo",
"merchant_category_code": 5411,
"merchant_guid": "MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b",
"merchant_location_guid": "MCL-00024e59-18b5-4d79-b879-2a7896726fea",
"metadata": "some metadata",
"original_description": "WHOLEFDS TSQ 102",
"posted_at": "2016-10-07T06:00:00.000Z",
"status": "POSTED",
"top_level_category": "Food & Dining",
"transacted_at": "2016-10-06T13:00:00.000Z",
"type": "DEBIT",
"updated_at": "2016-10-07T05:49:12.000Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"user_id": "partner-2345"
},
// •••
],
"pagination": {
"current_page": 1,
"per_page": 10,
"total_entries": 243,
"total_pages": 25
}
}
```
See [Instant Account Verification](/products/connectivity/instant-account-verification) for more info.
This sample response shows the data you can expect to get for account owners.
```json theme={null}
{
"account_numbers": [
{
"account_guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f38462",
"account_number": "10001",
"institution_number": null,
"member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"routing_number": "091000019",
"passed_validation": true,
"transit_number": null,
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 1,
"total_pages": 1
}
}
```
See [Account Owner Identification](/products/connectivity/account-owner-identification) for more info.
This sample response shows the data you can expect to get for account owners.
```json theme={null}
{
"account_owners": [
{
"account_guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f38462",
"address": "123 This Way",
"city": "Middlesex",
"country": "US",
"email": "donnie@darko.co",
"first_name": "Donnie",
"guid": "ACO-63dc7714-6fc0-4aa2-a069-c06cdccd1af9",
"last_name": "Darko",
"member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"owner_name": "Donnie Darko",
"phone": "555-555-5555",
"postal_code": "00000-0000",
"state": "VA",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 1,
"total_pages": 1
}
}
```
You can configure the widget to return transactions when its mode is set to `verification`.
This sample response shows the data you can expect to get for transactions.
```json theme={null}
{
"transactions": [
{
"account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
"account_id": "account123",
"amount": 61.11,
"category": "Groceries",
"category_guid": "CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8",
"check_number_string": "6812",
"created_at": "2016-10-06T09:43:42.000Z",
"currency_code": "USD",
"date": "2013-09-23T00:00:00.000Z",
"description": "Whole foods",
"extended_transaction_type": "partner_transaction_type",
"guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",
"id": "transaction-265abee9-889b-af6a-c69b-25157db2bdd9",
"is_bill_pay": false,
"is_direct_deposit": false,
"is_expense": true,
"is_fee": false,
"is_income": false,
"is_international": false,
"is_overdraft_fee": false,
"is_payroll_advance": false,
"is_recurring": false,
"is_subscription": false,
"latitude": -43.2075,
"localized_description": "This is a localized_description",
"localized_memo": "This is a localized_memo",
"longitude": 139.691706,
"member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"member_is_managed_by_user": false,
"memo": "This is a memo",
"merchant_category_code": 5411,
"merchant_guid": "MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b",
"merchant_location_guid": "MCL-00024e59-18b5-4d79-b879-2a7896726fea",
"metadata": "some metadata",
"original_description": "WHOLEFDS TSQ 102",
"posted_at": "2016-10-07T06:00:00.000Z",
"status": "POSTED",
"top_level_category": "Food & Dining",
"transacted_at": "2016-10-06T13:00:00.000Z",
"type": "DEBIT",
"updated_at": "2016-10-07T05:49:12.000Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"user_id": "partner-2345"
},
// •••
],
"pagination": {
"current_page": 1,
"per_page": 10,
"total_entries": 243,
"total_pages": 25
}
}
```
## Connection Errors
When the widget is loaded, it automatically chooses the best course of action for resolving a connection error between a user and their financial institution.
For more info, see [Member Connection Statuses](/api-reference/platform-api/reference/members#member-connection-statuses).
## Browser Support
MX supports HTML5-compliant browsers that support TLSv1.2 or higher. Older versions of supported browsers aren't explicitly tested. MX will review issues as reported, but upgrading may be required if compatibility can't be ensured.
### Supported Desktop Browsers
MX tests its web applications on the **current** version and **previous** version of the following browsers:
| Browser | PC | Mac |
| -------------- | --- | --- |
| Chrome | Yes | Yes |
| Microsoft Edge | Yes | N/A |
| Firefox | Yes | Yes |
| Safari | No | Yes |
**BLOCKED BROWSERS**
MX may actively block some browsers from displaying our products when the results would provide an extremely poor user experience. Browsers in Compatibility or Quirks mode may not function and can be blocked if performance is degraded.
### Supported Mobile Browsers
MX tests its web applications on the **current** version and **previous** version of iOS and Android, using the following browsers:
| Browser | iOS | Android |
| --------------- | --- | ------- |
| Chrome | No | Yes |
| Safari | Yes | N/A |
| WKWebView | Yes | N/A |
| Android WebView | N/A | Yes |
**NOTE**
UIWebView is no longer supported. Apple recommends using [WKWebView](https://developer.apple.com/documentation/uikit/uiwebview).
## Language Support
To change the display language from English, set the `Accept-Language` header in the [Request Widget URL](/api-reference/platform-api/reference/widgets) endpoint to one of these supported languages:
* `en-CA`
* `es`
* `fr`
## Widget Dimensions
The Connect Widget uses a responsive design. Layout and styles may adjust based on screen size, and certain elements may become hidden/visible at different widths.
The **minimum dimensions** supported for mobile and desktop platforms are:
* Height: 550px
* Width: 320px
Design changes may occur at the following **width breakpoints**, which are based on common device resolutions:
* Small: 320px–767px
* Medium: 768px–1199px
* Large: 1200px and higher
**NOTE**
Breakpoints and layout behavior are subject to change.
## OAuth Support
You must [register for OAuth](/resources/oauth-guide/#registration) before you can use it with real institutions.
For institutions using an OAuth flow, the Connect Widget will redirect to that institution's page or mobile app, where the end user can authorize the accounts they want to connect.
See [Connect Widget OAuth Workflows](/resources/oauth-guide/oauth-in-connect-widget).
## Handling Session Timeouts
When integrating our Connect Widget, consider the session timeout built into the widget and the session timeout built into your website or mobile app.
The widget automatically times out after 15 minutes of inactivity. Reach out to your account representative to customize this duration.
Thirty seconds before the timeout, a **No recent activity** screen appears and prompts the user to select **Continue** to avoid timing out. If no user activity is detected within those 30 seconds, the widget will timeout and display a **Session expired** screen.
## Member Use Cases
**NOTE**
Work with MX to enable this functionality.
You can opt in to setting the `use_cases` field in applicable requests so each `member` has an associated `use_case`. This ensures only the data associated with the use case for that member (PFM or Money Movement) is returned. It also lets you filter a user’s data through a single `use_case`, even if data relating to a different `use_case` is in our system.
If you’ve implemented the Connect Widget and have worked with MX to enable member use cases, you must include the `use_cases` field when [requesting your widget URL](/api-reference/platform-api/reference/widgets) to ensure:
* Each `member` is associated with a specific use case.
* Our Personal Finance Management and Financial Insights products reflect data only for members with the `PFM` use case.
* Members with `"use_cases": ["MONEY_MOVEMENT"]` do not aggregate transaction data.
In the Connect Widget, this change impacts the flow of new and existing members.
For more info about other changes relating to creating members, updating members, and available query parameters for use cases, see the [Platform API](/api-reference/platform-api/overview/formats-requirements#member-use-cases) docs.
### New Members
When you request a widget URL with a `widget_type` of `connect_widget` or `connections_widget`, set the `use_cases` field. The use cases provided in this request will be saved to any member created inside of the widget.
For example, if you:
1. Set `use_cases: ["PFM"]` in the widget URL request.
2. Load the Connect Widget using the URL returned from the request.
3. Successfully create a member.
4. Read that member, which will have a `use_case` of `PFM` as set in step 1.
### Existing Members
The widget won’t remove use cases from an existing member, it will only add new ones.
For example, let’s assume a member already exists that has `use_cases: ["MONEY_MOVEMENT"]`:
1. You set `use_cases: ["PFM"]` in the widget URL request.
2. The end user finds their institution and enters their same credentials as before.
3. The widget will update the existing member so to have `use_cases: [“MONEY_MOVEMENT”, "PFM"]`.