Institutions Overview
Institutions represent a financial institution.
A single real-world financial institution may have several institution objects on the MX platform.
For example, the mortgage division of a financial institution might use a separate system than its everyday banking division, which is different from its credit card division.
Only MX can create an institution. Each institution can offer multiple connection methods such as:
- An email and a password
- A username and a password
- OAuth (some institutions don’t support OAuth)
When creating a member, you must also call List Institution Credentials to retrieve the set of required credentials for each institution and request them from the user.
You can Read an Institution to see what products each institution supports and access an institution’s:
- Logos
- URLs for things such as forgotten usernames and passwords
- Instructional text (we use this in our Connect Widget to help give further context on any caveats users may encounter when attempting to connect to the institution)
The list of institutions can change at any time.
Caching our Institutions List and Credentials
You can use the List Institutions endpoint to retrieve a list of all institutions currently available in the MX platform.
To avoid frequent calls that return all supported institutions, we recommend caching the institution list and the required credentials for each institution daily. This ensures you pick up new institutions and any changes to existing ones, such as updated required credentials when MX switches to a new data provider.
We aim to maintain the same institution guid even if we change data providers, but in rare cases, it may change.
Institution Fields
| Field | Data Type | Description |
|---|---|---|
client_status | String | The client-level status of the institution, indicating restrictions on member connections. See Client Status for more details. |
code | String | A unique identifier for each institution, defined by MX. |
created_at | String | Date and time the institution was created, represented in ISO 8601 format with timestamp (e.g. 2015-04-13T12:01:23-00:00). |
forgot_password_url | String | The URL of the institution for helping users recover a forgotten password. |
forgot_username_url | String | The URL of the institution for helping users recover a forgotten username. |
guid | String | A unique identifier for the institution. Defined by MX. |
instructional_text | String | Text intended to help end users provide the correct credentials when creating a new member. May contain <a></a> tags to link to explanatory material. Partners should render this text when end users are asked for their credentials. |
instructional_text_steps | Array | An array of instructional steps that may contain html elements. |
is_disabled_by_client | Boolean | This indicates whether the institution has been disabled by the client. |
is_hidden | Boolean | If the institution is available for creating new member connections, this field will be false. Otherwise, this field will be true. |
iso_country_code | String | The ISO country code related to the institution. Can also be used as a query param (array) on the List Institution endpoints to filter the institutions. |
medium_logo_url | String | The URL for a 100px X 100px logo for each institution. A generic logo is returned for institutions that don't have one. |
name | String | An easy-to-read name for an institution, for example, "Chase Bank" or "Wells Fargo Bank." |
small_logo_url | String | The URL for a 50px X 50px logo for each institution. A generic logo is returned for institutions that don't have one. |
status | String | The operational status of the institution. See Institution Status for more details. |
supports_account_identification | Boolean | This indicates whether the institution supports account identification. |
supports_account_statement | Boolean | This indicates whether the institution provides access to account statements. |
supports_account_verification | Boolean | This indicates whether the institution supports account verification. |
supports_oauth | Boolean | This reflects two conditions. This will be true when both:
|
supports_tax_document | Boolean | This indicates whether the institution supports tax documents. |
supports_transaction_history | Boolean | Indicates whether extended transaction history is supported. See the Extended Transaction History guide for more info. |
trouble_signing_in_url | String | The URL of the institution for helping users troubleshoot any other sign-in issue. |
url | String | The URL for particular institution's website , e.g., www.chase.com. |
Status
The institution object provides two fields that clarify the status of that institution:
institution.statusrepresents the global status of the institution across MX.institution.client_statusrepresents the institution status specifically for your client configuration. This allows MX tooling to apply client-level rules without affecting global institution behavior.
Use these fields to:
- Differentiate between the institution ’s overall status and the status for your specific integration.
- Control which institutions are shown to users based on these status values.
- Display clearer messages to your users when an institution is unavailable, has known issues, or is otherwise restricted.
Use the following workflow to provide clearer messaging around institution status to end users:
- Update your institution-related API integrations to read
statusandclient_statuswhere applicable. - Map each relevant status value to appropriate user-facing messages consistent with your brand and regulatory requirements. If
statusindicates that an institution is unavailable, you may choose to hide it from search results or show a clear, neutral message explaining that the institution cannot be connected at this time. Ifclient_statusindicates that aninstitutionis blocked or restricted for yourclient, provide a concise, neutral explanation without disclosing internal reasons or sensitive details.
Institution Status
The institution.status field represents the global status of the institution across MX.
| Status | Behavior | Message |
|---|---|---|
OPERATIONAL | Operations allowed | None |
MAINTENANCE | All operations blocked | This institution is temporarily unavailable due to scheduled system maintenance. Access will resume once maintenance is complete. Please try again later. |
DEGRADED | Operations allowed (with warning) | This institution is experiencing connectivity issues. You can still try to connect, but may need to try again later. |
UNAVAILABLE | All operations blocked | This institution is experiencing technical issues that are preventing successful connections. It's unclear when this will be resolved. |
Client Status
The institution.client_status field represents the institution's status for your client configuration. This allows MX tooling to apply client-level rules without affecting global institution behavior. When checking if an operation is allowed, client_status is evaluated first, then institution.status. If either field blocks the operation, a 400 Bad Request error is returned with the appropriate message in the error.message field.
| Client Status | Blocks | Message |
|---|---|---|
AVAILABLE | No restrictions | None |
PREVENT_ALL | New member creation and updates to existing members | The requested data isn't available through this institution. |
PREVENT_NEW | New member creation only | This institution is not available for connection. |
PREVENT_ALL_AND_DISCONNECT | New member creation and updates to existing members | This institution is not available for connection. |
PREVENT_VERIFICATION | New member creation when member.data_request.products is set to account_verification and calls to POST /users/{user_identifier}/members/{member_identifier}/verify | The requested data isn't available through this connection. |
PREVENT_BACKGROUND_AGG | No restrictions (for informational purposes) | None |