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.

note

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 services and 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. Other endpoints can continue using the standard API versioning header: application/vnd.mx.api.v1+json.

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.

_10

curl -L -X POST `https://int-api.mx.com/endpoint' \

_10

-H 'Content-Type: application/json' \

_10

-H 'Accept: application/vnd.mx.api.v1+json; 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.

Product	Value
Instant Account Verification	account_verification
Account Owner Identification	identity_verification
Account Aggregation	transactions
Extended History	history
Statements	statements
Investments	investments

note

Real Time Balance isn't a declarable product through Unified Product Ordering. Balance data is considered a required data type for all products so it's not needed during initialization.

Aggregate Multiple Products

To use this functionality in the Connect Widget:

1. 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.
2. Display this widget URL to the end user.
3. Wait for the end user to connect to an institution and create a member.
4. Verify aggregation is complete by polling the member's connection_status and is_being_aggregated fields.
5. 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 (history): List Transactions by Member or use another GET Transactions endpoint
   • Statements (statements): Read Statement by Member or List Statements by Member
   • Investments (investments): List Holdings by Member or use another GET Investment Holdings endpoint

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.