> ## 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. # Integrate without using MX's Connect Widget By the end of this guide, you'll be able to connect a user to their financial institution and retrieve their financial data using the Platform API to power a non-MX UI connection experience. **LOOKING FOR OUR LEGACY GUIDES?** If you're using Platform API v2011101, see [Legacy Guides](/other/legacy-connectivity-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](/products/connectivity/overview/connectivity-integration-guides/#creating-users) * You have your own end-user facing connection experience instead of using our Connect Widget * You have [registered for OAuth](/resources/oauth-guide/#registration), unless you're using our test institution * You've set up how you'll [send held data](/products/connectivity/overview/held-data/) to MX (if your institution has held data) ## 1. Search for an Institution To connect a user to a specific financial institution, you first need to find that institution in MX's institution list. Make a GET request to the [List Institutions](/api-reference/platform-api/reference/list-institutions) endpoint and set the `name` query parameter to list only institutions in which the appended string appears. You can also check which institutions support the products (data) you need before connecting users by using the `supported_products` parameter with the [List Institutions](/api-reference/platform-api/reference/list-institutions). The response returns a paginated list of institutions, filtered by the query parameters you set. The next step covers which fields to look for in the response. **INFO** For caching the institutions list to improve performance, see [Caching our Institutions List and Credentials](/api-reference/platform-api/reference/institutions#caching-our-institutions-list-and-credentials). ```shell Request theme={null} curl -i -X GET 'https://int-api.mx.com/institutions?name=mx' \ -u 'client_id:api_key' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Accept-Version: v20250224' ``` ```json Response theme={null} { "institutions": [ { "code": "mxbank", "created_at": "2025-02-13T18:08:00+00:00", "forgot_password_url": "https://example.url.mxbank.com/forgot-password", "forgot_username_url": "https://example.url.mxbank.com/forgot-username", "guid": "INS-1572a04c-912b-59bf-5841-332c7dfafaef", "instructional_text": "Some instructional text for end users.", "instructional_text_steps": [ "Step 1: Do this.", "Step 2: Do that." ], "is_disabled_by_client": false, "is_hidden": true, "iso_country_code": "US", "medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png", "name": "MX Bank", "small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png", "supported_products": [ "account_verification" ], "supports_oauth": true, "supports_tax_document": true, "trouble_signing_in_url": "https://example.url.mxbank.com/login-trouble", "url": "https://www.mxbank.com" } ], "pagination": { "current_page": 1, "per_page": 25, "total_entries": 1, "total_pages": 1 } } ``` ## 2. Get the Institution's Requirements The response from the previous step included a `supports_oauth` field that reflects 2 conditions: 1. The institution supports OAuth. 2. You have gone through the [OAuth registration process](https://dashboard.mx.com/oauth-settings). If this field is `true`, you must create an OAuth member in the next step. If this field is `false`, make a request to the [List Institution Credentials](/api-reference/platform-api/reference/list-institution-credentials) endpoint and set the institution `code` from the previous step in the path. The following example uses `mxbank` as the `code` and returns the `guid` for each required credential, which you'll use to match the end user's credentials to the required credential types. ```shell Request theme={null} curl -i -X GET 'https://int-api.mx.com/institutions/mxbank/credentials' \ -u 'client_id:api_key' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Accept-Version: v20250224' ``` ```json Response theme={null} { "credentials": [ { "display_order": 1, "field_name": "LOGIN", "field_type": "LOGIN", "guid": "CRD-9f61fb4c-912c-bd1e-b175-ccc7f0275cc1", "label": "Username", "type": "TEXT" }, { "display_order": 2, "field_name": "PASSWORD", "field_type": "PASSWORD", "guid": "CRD-e3d7ea81-aac7-05e9-fbdd-4b493c6e474d", "label": "Password", "type": "TEXT" } ], "pagination": { "current_page": 1, "per_page": 25, "total_entries": 2, "total_pages": 1 } } ``` ## 3. Create Member Now that you have the institution's authentication requirements, create the `member` and specify the data to retrieve after the connection is established. The products you set in the Create Member request (through the `data_request.products`) determine what data will be aggregated. If the institution's `supports_oauth` field is `true`, create an OAuth member (see our [OAuth guides](/resources/oauth-guide#guides)). Otherwise, create a credential-based member as shown below. To create a credential-based member, you need the `user_guid`, `institution_code`, and credential values from the end user. The following example uses MX Bank test credentials (username: `mxuser`, password: `password`). Make a request to the [Create Member](/api-reference/platform-api/reference/create-member) endpoint (`POST /users/{user_guid}/members`): * **Required:** Put the `user_guid` in the path. * **Required:** Include the credential GUIDs and their values in the `credentials` array. * **Required:** Set `data_request.products` to define the data you want to aggregate. * **Recommended:** Set `id` to a unique value when creating a member so you can sync between your systems and ours. * **Recommended:** Set `metadata`. * **Optional:** Disable background aggregation by setting `background_aggregation_is_disabled` to `true`. For more info, see [Background Aggregation](#). The response returns with the newly created `member` and indicates that the connection process has started: `connection_status` is `CREATED` and `is_being_aggregated` is `true`. **WARNING** Don't add multiple members that connect to the same `institution` using the same `credentials` on the same `user`. This will result in a `409 Conflict` error. ```shell Request theme={null} curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members' \ -u 'client_id:api_key' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Accept-Version: v20250224' \ -d '{ "member": { "credentials": [ { "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da", "value": "mxuser" }, { "guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da", "value": "password" } ], "id": "member-9876", "institution_code": "mxbank", "metadata": "some metadata" } }' ``` ```json Response theme={null} { "member": { "aggregated_at": null, "background_aggregation_is_disabled": false, "connection_status": "CREATED", "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0", "id": "member-9876", "institution_code": "mxbank", "is_being_aggregated": false, "is_managed_by_user": true, "is_oauth": false, "metadata": "some metadata", "name": "MX Bank", "successfully_aggregated_at": null, "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c", "user_id": "partner-2345" } } ``` ## 4. 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](/api-reference/platform-api/reference/members#member-connection-statuses). ## 5. Ensure Data Aggregated To ensure that the member is in a state where you can retrieve data, you must implement a polling workflow: 1. Request the [Read Member Status](/api-reference/platform-api/reference/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. ## 6. Read Data Once the member's `connection_status` is `CONNECTED` and `is_being_aggregated` is `false`, retrieve the data using the endpoints below. **INFO** Not every field will populate for each product, as data availability depends on what the institution provides. | Requested Data | Retrieve Data | | :------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `accounts` and/or `transactions` | [List Accounts](/api-reference/platform-api/reference/list-user-accounts), [List Member Accounts](/api-reference/platform-api/reference/list-member-accounts), [Read Account](/api-reference/platform-api/reference/read-account), [Read Account by Member](/api-reference/platform-api/reference/read-account-by-member), [List Transactions by Account](/api-reference/platform-api/reference/list-transactions-by-account), [List Transactions](/api-reference/platform-api/reference/list-transactions), or [Read Transaction](/api-reference/platform-api/reference/read-transaction) | | `identification` | [List Account Owners by Member](/api-reference/platform-api/reference/list-account-owners-by-member) | | `verification` | [List Account Numbers by Member](/api-reference/platform-api/reference/list-account-numbers-by-member) or [List Account Numbers by Account](/api-reference/platform-api/reference/list-account-numbers-by-account) | | `statements` | 1. [List Statements by Member](/api-reference/platform-api/reference/list-statements-by-member) or [Read Statement by Member](/api-reference/platform-api/reference/read-statement-by-member)
2. (Optional) [Download Statement PDF](/api-reference/platform-api/reference/download-statement-pdf) | | `transaction_history` | 1. [List Member Accounts](/api-reference/platform-api/reference/list-member-accounts), [Read Account](/api-reference/platform-api/reference/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](/api-reference/platform-api/reference/list-transactions-by-account) | | `investments` | [List Holdings by Member](/api-reference/platform-api/reference/list-holdings-by-member), [List Holdings by User](/api-reference/platform-api/reference/list-holdings-by-user), [List Holdings by Account](/api-reference/platform-api/reference/list-holdings-by-account), or [Read Holding](/api-reference/platform-api/reference/read-holding) | | `rewards` | [List Rewards](/api-reference/platform-api/reference/list-rewards) or [Read Reward](/api-reference/platform-api/reference/read-reward) | ## 7. Update Data Later **NOTE** MX automatically aggregates account and transaction data approximately every 24 hours. Check the `successfully_aggregated_at` field to determine if manual aggregation is needed. To refresh data after the initial connection: 1. Make a `POST` request using the appropriate endpoint from the table below. 2. Verify aggregation is complete using the workflow from step 5. 3. Retrieve the updated data. | Requested Data | Aggregate Data | Retrieve Data | | :---------------------------- | :------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `accounts` and `transactions` | [Aggregate Member](/api-reference/platform-api/reference/aggregate-member) | [List Accounts](/api-reference/platform-api/reference/list-user-accounts), [List Member Accounts](/api-reference/platform-api/reference/list-member-accounts), [Read Account](/api-reference/platform-api/reference/read-account), [Read Account by Member](/api-reference/platform-api/reference/read-account-by-member), [List Transactions by Account](/api-reference/platform-api/reference/list-transactions-by-account), [List Transactions](/api-reference/platform-api/reference/list-transactions), or [Read Transaction](/api-reference/platform-api/reference/read-transaction) | | `identification` | [Identify Member](/api-reference/platform-api/reference/identify-member) | [List Account Owners by Member](/api-reference/platform-api/reference/list-account-owners-by-member) | | `verification` | [Verify Member](/api-reference/platform-api/reference/verify-member) | [List Account Numbers by Member](/api-reference/platform-api/reference/list-account-numbers-by-member) or [List Account Numbers by Account](/api-reference/platform-api/reference/list-account-numbers-by-account) | | `statements` | [Fetch Statements](/api-reference/platform-api/reference/fetch-statements) | 1. [List Statements by Member](/api-reference/platform-api/reference/list-statements-by-member) or [Read Statement by Member](/api-reference/platform-api/reference/read-statement-by-member)
2. (Optional) [Download Statement PDF](/api-reference/platform-api/reference/download-statement-pdf) | | `transaction_history` | [Extend History](/api-reference/platform-api/reference/extend-history) | 1. [List Member Accounts](/api-reference/platform-api/reference/list-member-accounts), [Read Account](/api-reference/platform-api/reference/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](/api-reference/platform-api/reference/list-transactions-by-account) | | `investments` | [Aggregate Member](/api-reference/platform-api/reference/aggregate-member) | [List Holdings by Member](/api-reference/platform-api/reference/list-holdings-by-member), [List Holdings by User](/api-reference/platform-api/reference/list-holdings-by-user), [List Holdings by Account](/api-reference/platform-api/reference/list-holdings-by-account), or [Read Holding](/api-reference/platform-api/reference/read-holding) | | `rewards` | [Fetch Rewards](/api-reference/platform-api/reference/fetch-rewards) | [List Rewards](/api-reference/platform-api/reference/list-rewards) or [Read Reward](/api-reference/platform-api/reference/read-reward) | **SUCCESS** You've used our Platform API to build connections between a user and their financial institution and can retrieve data from that connection.