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