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.
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 your own end-user facing connection experience instead of using our Connect Widget
- You have registered for OAuth, unless you're using our test institution
- You've set up how you'll send held data to MX (if your institution has held data)
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 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.
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.
For caching the institutions list to improve performance, see Caching our Institutions List and Credentials.
Get the Institution's Requirements
The response from the previous step included a supports_oauth field that reflects 2 conditions:
- The institution supports OAuth.
- You have gone through the OAuth registration process.
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 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.
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). Otherwise, create a credential-based member as shown below.
Create a credential-based member
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 endpoint (POST /users/{user_guid}/members):
- Required: Put the
user_guidin the path. - Required: Include the credential GUIDs and their values in the
credentialsarray. - Required: Set
data_request.productsto define the data you want to aggregate. - Recommended: Set
idto 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_disabledtotrue. 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.
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.
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.
Ensure Data Aggregated
To ensure that the member is in a state where you can retrieve data, you must implement a polling workflow:
- Request the Read Member Status endpoint.
- In the response, check the
connection_statusandis_being_aggregatedfields. - If
connection_statusisCONNECTEDandis_being_aggregatedisfalse, exit this workflow and retrieve the data. If not, we recommend waiting 3 seconds before repeating this polling workflow.
Read Data
Once the member's connection_status is CONNECTED and is_being_aggregated is false, retrieve the data using the endpoints below.
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, List Accounts by Member, Read Account, Read Account by Member, List Transactions by Account, List Transactions, or Read Transaction |
identification | List Account Owners by Member |
verification | List Account Numbers by Member or List Account Numbers by Account |
statements | 1. List Statements by Member or Read Statement by Member 2. (Optional) Download Statement PDF |
transaction_history | 1. List Accounts by Member, 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 |
investments | List Holdings by Member, List Holdings by User, List Holdings by Account, or Read Holding |
rewards | List Rewards or Read Reward |
Update Data Later
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:
- Make a
POSTrequest using the appropriate endpoint from the table below. - Verify aggregation is complete using the workflow from step 5.
- Retrieve the updated data.
| Requested Data | Aggregate Data | Retrieve Data |
|---|---|---|
accounts and transactions | Aggregate Member | List Accounts, List Accounts by Member, Read Account, Read Account by Member, List Transactions by Account, List Transactions, or Read Transaction |
identification | Identify Member | List Account Owners by Member |
verification | Verify Member | List Account Numbers by Member or List Account Numbers by Account |
statements | Fetch Statements | 1. List Statements by Member or Read Statement by Member 2. (Optional) Download Statement PDF |
transaction_history | Extend History | 1. List Accounts by Member, 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 |
investments | Aggregate Member | List Holdings by Member, List Holdings by User, List Holdings by Account, or Read Holding |
rewards | Fetch Rewards | List Rewards or Read Reward |
You've used our Platform API to build connections between a user and their financial institution and can retrieve data from that connection.