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 v20111101, 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)

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 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 products[] query parameter with the List Institutions endpoint. 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.

INFOFor caching the institutions list to improve performance, see Caching our Institutions List and Credentials.

GET /institutions?name=mx

Response

{
  "institutions": [
    {
      "code": "mxbank",
      "guid": "INS-1572a04c-912b-59bf-5841-332c7dfafaef",
      "iso_country_code": "US",
      "name": "MX Bank",
      "products": [
        "account_verification"
      ],
      "self": "/institutions/INS-1572a04c-912b-59bf-5841-332c7dfafaef",
      "supports_oauth": true,
      "mx_record": {
        "created_at": "2025-02-13T18:08:00Z",
        "updated_at": "2025-02-13T18:08:00Z"
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

2. Get the Institution’s Requirements

The institution returned in step 1 includes 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 step 3. If this field is false, make a request to the List Institution Credentials endpoint and set the institution code from step 1 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. GET /institutions/mxbank/credentials

Response

{
  "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 (the MX resource that represents a user’s connection to one financial institution) 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 by setting is_oauth to true, then direct the user to the oauth.authorization_url in the response (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_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: member_status.status is CREATED.

WARNINGDon’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.

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members' \
-d '{
      "data_request": {
        "products": [
          "account_verification"
        ]
      },
      "member": {
        "credentials": [
          {
            "guid": "CRD-9f61fb4c-912c-bd1e-b175-ccc7f0275cc1",
            "value": "mxuser"
          },
          {
            "guid": "CRD-e3d7ea81-aac7-05e9-fbdd-4b493c6e474d",
            "value": "password"
          }
        ],
        "id": "member-9876",
        "institution_code": "mxbank",
        "metadata": "some metadata"
      }
    }'

{
  "member": {
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "id": "member-9876",
    "metadata": "some metadata",
    "name": "MX Bank",
    "self": "/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "institution": {
      "code": "mxbank",
      "guid": "INS-1572a04c-912b-59bf-5841-332c7dfafaef",
      "iso_country_code": "US",
      "name": "MX Bank",
      "products": [
        "account_verification"
      ],
      "self": "/institutions/INS-1572a04c-912b-59bf-5841-332c7dfafaef"
    },
    "member_status": {
      "status": "CREATED",
      "error": null,
      "self": "/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/status"
    },
    "oauth": {
      "is_oauth": false,
      "authorization_url": null,
      "self": "/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/oauth/authorization_url"
    },
    "user": {
      "guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
      "id": "partner-2345",
      "metadata": null,
      "self": "/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    }
  }
}

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 (member_status.status) of each member that belongs to a user. For guidance on how to handle each possible status, see 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:

Request the Read Member Status endpoint.
In the response, check the member_status.status and products.last_updated_at fields.
If member_status.status is CONNECTED and products.last_updated_at is later than when you started the request, exit this workflow and retrieve the data. If not, we recommend waiting 3 seconds before repeating this polling workflow.

6. Read Aggregated Data

Once the member’s member_status.status is CONNECTED and products.last_updated_at is later than when you started the request, 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
`transactions`	List Accounts, List Member Accounts, Read Account, Read Account by Member, List Transactions by Account, List Transactions, or Read Transaction
`identity_verification`	List Account Owners by Member
`account_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 Member Accounts, 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

7. Update Aggregated Data Later

MX automatically aggregates account and transaction data approximately every 24 hours. Check the products.last_updated_at field in the Read Member Status response to determine if manual aggregation is needed.

To refresh data after the initial connection:

Make a POST request 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
`transactions`	Aggregate Transactions	List Accounts, List Member Accounts, Read Account, Read Account by Member, List Transactions by Account, List Transactions, or Read Transaction
`identity_verification`	Identity Verification	List Account Owners by Member
`account_verification`	Account Verification	List Account Numbers by Member or List Account Numbers by Account
`statements`	Aggregate Statements	1. List Statements by Member or Read Statement by Member 2. (Optional) Download Statement PDF
`transaction_history`	Aggregate Transaction History	1. List Member Accounts, 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 Transactions	List Holdings by Member, List Holdings by User, List Holdings by Account, or Read Holding

You’ve used our Platform API to build connections between a user and their financial institution and can retrieve data from that connection.

​Prerequisites

​1. Search for an Institution

​2. Get the Institution’s Requirements

​3. Create Member

​4. Monitor Connection Statuses

​5. Ensure Data Aggregated

​6. Read Aggregated Data

​7. Update Aggregated Data Later

Prerequisites

1. Search for an Institution

2. Get the Institution’s Requirements

3. Create Member

4. Monitor Connection Statuses

5. Ensure Data Aggregated

6. Read Aggregated Data

7. Update Aggregated Data Later