Institutions Overview - MX Documentation

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 the institution supports OAuth and you have been properly registered with that institution.
`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.status represents the global status of the institution across MX.
institution.client_status represents 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 status and client_status where applicable.
Map each relevant status value to appropriate user-facing messages consistent with your brand and regulatory requirements. If status indicates 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. If client_status indicates that an institution is blocked or restricted for your client, 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

​Caching our Institutions List and Credentials

​Institution Fields

​Status

​Institution Status

​Client Status

Caching our Institutions List and Credentials

Institution Fields

Status

Institution Status

Client Status