Intro to Unified Product Ordering
If you’re using the Platform API, you can include a version header for version 20250224 to aggregate data from multiple products in a single API call.
This uses a future Platform API version, different than what's shown in the rest of our guides.
What's Changed?
The following endpoints are impacted with v20250224:
- List Institutions:
GET /institutions: Enhanced search and filtering capabilities based on the products supported by each institution. - Read Institution:
GET /institutions/{institution_code}: More information provided about the products supported by the institution. - Create Member:
POST /users/{user_guid}/members: Initiate the aggregation of any products specified in the request. - Request Widget URL:
POST /users/{user_guid}/widget_urls: Initiate the aggregation of any products specified in the request.
Make sure to use the new version header for each of these endpoints.
How To Access
The MX Platform API requires basic access authentication using your client_id and api_key. These credentials must be Base64 encoded and included in the Authorization header of each API request to ensure secure access.
To access this functionality, modify the request header to specify this version: v20250224.
Here’s an example using curl to access v20250224. Replace https://int-api.mx.com/endpoint with the actual API endpoint you wish to access and your Base64 encoded client_id and api_key.
_10curl -L -X POST `https://int-api.mx.com/endpoint' \_10-H 'Content-Type: application/json' \_10-H 'Accept: application/json' \_10-H 'Accept-Version: v20250224' \_10-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}'
Defining Products
You can define the products using the following values in query parameters and request fields.
Balance data is always included and doesn't need to be set.
| Product | Value |
|---|---|
| Instant Account Verification | account_verification |
| Account Owner Identification | identity_verification |
| Account Aggregation | transactions |
| Extended History | transaction_history |
| Statements | statements |
| Investments | investments |
Aggregate Multiple Products
To use this functionality in the Connect Widget:
- Call the Request Widget URL endpoint:
- Change the Authorization header to access
v20250224. - Define the products you want to aggregate. This only starts the aggregation process, so in the next steps you'll retrieve that aggregated data.
- Change the Authorization header to access
- Display this widget URL to the end user.
- Wait for the end user to connect to an institution and create a member.
- Verify aggregation is complete by polling the member's
connection_statusandis_being_aggregatedfields. - Use one of the following endpoints to fetch that aggregated data:
- Instant Account Verification (
account_verification): List Account Numbers by Member or List Account Numbers by Account - Account Owner Identification (
identity_verification): List Account Owners by Member - Account Aggregation (
transactions): List Accounts or List Transaction by Account - Extended History (
transaction_history): List Transactions by Member or use anotherGETTransactions endpoint - Statements (
statements): Read Statement by Member or List Statements by Member - Investments (
investments): List Holdings by Member or use anotherGETInvestment Holdings endpoint
- Instant Account Verification (
Accessing Priority Data
This feature is in beta. The documentation is subject to change as updates are made.
When requesting products, you can optionally retrieve priority data before all requested data has aggregated. This helps:
- Reduce user drop-off during the connection flow
- Power time-sensitive workflows such as account verification or balance display
Priority data always includes a list of accounts with core details (name, type, and balance if available). Depending on what products you set, it may include account numbers and account owners.
You’ll know when priority data is ready via:
- Widget event
- Webhook (reach out to MX to enable)
The widget event and webhook may not be supported by all institutions.
You can retrieve the priority data using the identifiers sent in the widget event and webhook, then close the Connect Widget while non-priority data aggregates in the background.
When aggregation for every requested product is complete, the Member webhook will send (if enabled) and the Connect Widget will send the Member Connected event.
The following table outlines what data is available initially (via widget event or webhook) and what data arrives later.
| Products Requested | Priority Data | Data Available Later |
|---|---|---|
account_verification | Accounts list with core details (name, type, and balance if available) | Account balances and account numbers |
account_verification + identity_verification | Accounts list with core details (name, type, and balance if available) | Account balances, account numbers, and account owners |
account_verification + identity_verification + transactions | Account numbers, account owners, and accounts list with core details (name, type, and balance if available) | Account balances and transactions |
account_verification + transactions | Account numbers and accounts list with core details (name, type, and balance if available) | Account balances and transactions |
identity_verification | Accounts list with core details (name, type, and balance if available) | Account balances and account owners |
identity_verification + transactions | Account owners and accounts list with core details (name, type, and balance if available) | Account balances and transactions |
transactions | Accounts list with core details (name, type, and balance if available) | Account balances and transactions |
Impact on Conversion
Specifying multiple products within the products array restricts the selection to institutions that support all the specified services. This selective visibility ensures that users interact only with institutions capable of fulfilling their complete service requirements, enhancing the efficiency and success rate of connections.
Further benefits are:
- Streamlined Consent Process: By requesting all necessary permissions during a single OAuth flow, the consent process becomes more straightforward for users. This approach reduces the likelihood of user drop-off caused by complicated consent adjustments.
- Optimized Data Retrieval: Initializing all required products during the connection setup allows MX to commence data fetching immediately. This approach shortens the wait time for data availability and organizes the data retrieval process more efficiently, prioritizing the fetch sequence according to the integration needs.
Example Scenario
Suppose you configure the Connect Widget or API to require both Instant Account Verification (account_verification) and Account Owner Identification (identity_verification):
- Institution Availability: Only institutions that support both verification services will be displayed to the user. This filter prevents scenarios where a user attempts to connect with an institution that cannot provide the necessary services.
- OAuth Permissions: If the institution uses OAuth and supports configuring Account Owner data access as a separate permission, users must grant explicit consent for both services. Failure to do so triggers an error, prompting the user to revisit the OAuth flow and adjust their permissions. This ensures that all necessary data accesses are authorized from the outset.
Identifying Product Availability
To ensure the data is available for your desired institution, use the supported_products parameter in the List Institutions and Read Institution endpoints.