Institutions endpoints
Fetch data about supported institutions
The interface for these endpoints has changed in API version 2020-09-14. If you are using an older API version, see API versioning.
Introduction
Institutions endpoints support querying all institutions, as well as looking up a single institution to retrieve up-to-date information about its health status and capabilities. This can be useful for apps whose business logic may depend on institution capabilities, such as Payment Initiation.
API-provided institution health data can also be used for in-app UIs. For example, Personal Financial Management (PFM) apps can help set user expectations around data availability by showing dashboard data displaying the health of a user's connected institutions, in conjunction with personalized Item last updated data from /item/get.
For non-programmatic access to institution information, the status dashboard provides a browsable view of institutions, supported products, and institution health.
Institution coverage
To see which institutions are supported, or to look up the status of a specific institution, use the Institution status dashboard. You can also query this information programmatically via the /institutions/get and /institutions/search endpoints.
To see which institutions support a particular product, use /institutions/get and specify the product in the options.products array.
Supported countries
Plaid supports over 12,000 institutions across North America and Europe.
For a list of which products are supported for each country, see supported products by country or the docs for the specific product you are interested in. For Identity Verification, over 200 countries are supported; for more details, see Identity Verification supported countries.
For details of institution coverage in Europe, see the European Coverage Explorer.
By default, customers in the United States and Canada receive access to institutions in all countries in Sandbox, and to United States and Canada in Production. To gain access to additional countries in Production, file a product access Support ticket.
| Endpoints | |
|---|---|
/institutions/get | Get a list of all supported institutions meeting specified criteria |
/institutions/get_by_id | Get details about a specific institution |
/institutions/search | Look up an institution by name |
Endpoints
/institutions/get
Get details of all supported institutions
Returns a JSON response containing details on all financial institutions currently supported by Plaid. Because Plaid supports thousands of institutions, results are paginated.
If there is no overlap between an institution’s enabled products and a client’s enabled products, then the institution will be filtered out from the response. As a result, the number of institutions returned may not match the count specified in the call.
Request fields
client_idstring
Your Plaid API
client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.secretstring
Your Plaid API
secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.countrequiredinteger
The total number of Institutions to return.
Minimum:
1 Maximum:
500 offsetrequiredinteger
The number of Institutions to skip.
Minimum:
0 country_codesrequired[string]
Specify which country or countries to include institutions from, using the ISO-3166-1 alpha-2 country code standard.
In API versions 2019-05-29 and earlier, the
In API versions 2019-05-29 and earlier, the
country_codes parameter is an optional parameter within the options object and will default to [US] if it is not supplied.Min items:
1 Possible values:
US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT, BE, AT, FIoptionsobject
An optional object to filter
/institutions/get results.products[string]
Filter the Institutions based on which products they support. Will only return institutions that support all listed products. When filtering based on
auth, an institution must support Instant Auth to match the criterion.Min items:
1 Possible values:
assets, auth, balance, employment, identity, cra_base_report, cra_income_insights, cra_network_insights, cra_partner_insights, income_verification, identity_verification, investments, liabilities, payment_initiation, standing_orders, transactions, transferrouting_numbers[string]
Specify an array of routing numbers to filter institutions. The response will only return institutions that match all of the routing numbers in the array. Routing number records used for this matching are generally comprehensive; however, failure to match a given routing number to an institution does not necessarily mean that the institution is unsupported by Plaid.
oauthboolean
Limit results to institutions with or without OAuth login flows. Note that institutions will have
oauth set to true if some Items associated with that institution are required to use OAuth flows; institutions in a state of migration to OAuth will have the oauth attribute set to true.include_optionalboolean
When
Note that Plaid does not own any of the logos shared by the API, and that by accessing or using these logos, you agree that you are doing so at your own risk and will, if necessary, obtain all required permissions from the appropriate rights holders and adhere to any applicable usage guidelines. Plaid disclaims all express or implied warranties with respect to the logos.
true, return the institution's homepage URL, logo and primary brand color. Not all institutions' logos are available.Note that Plaid does not own any of the logos shared by the API, and that by accessing or using these logos, you agree that you are doing so at your own risk and will, if necessary, obtain all required permissions from the appropriate rights holders and adhere to any applicable usage guidelines. Plaid disclaims all express or implied warranties with respect to the logos.
include_auth_metadataboolean
When
true, returns metadata related to the Auth product indicating which auth methods are supported.Default:
false include_paymentboolean
When
true, returns metadata related to the Payment Initiation product indicating which payment configurations are supported.Default:
false Select group for content switcher
1// Pull institutions2const request: InstitutionsGetRequest = {3 count: 10,4 offset: 0,5 country_codes: ['US'],6};7try {8 const response = await plaidClient.institutionsGet(request);9 const institutions = response.data.institutions;10} catch (error) {11 // Handle error12}Response fields and example
institutions[object]
A list of Plaid institutions
institution_idstring
Unique identifier for the institution. Note that the same institution may have multiple records, each with different institution IDs; for example, if the institution has migrated to OAuth, there may be separate
institution_ids for the OAuth and non-OAuth versions of the institution. Institutions that operate in different countries or with multiple login portals may also have separate institution_ids for each country or portal.namestring
The official name of the institution.
products[string]
A list of the Plaid products supported by the institution. Note that only institutions that support Instant Auth will return
auth in the product array; institutions that do not list auth may still support other Auth methods such as Instant Match or Automated Micro-deposit Verification. To identify institutions that support those methods, use the auth_metadata object. For more details, see Full Auth coverage. The income_verification product here indicates support for Bank Income.Possible values:
assets, auth, balance, balance_plus, beacon, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, standing_orders, transfer, employment, recurring_transactions, transactions_refresh, signal, statements, processor_payments, processor_identity, profile, cra_base_report, cra_income_insights, cra_partner_insights, cra_network_insights, cra_cashflow_insights, layer, pay_by_bank, protect_linked_bankcountry_codes[string]
A list of the country codes supported by the institution.
Possible values:
US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT, BE, AT, FIurlnullablestring
The URL for the institution's website
primary_colornullablestring
Hexadecimal representation of the primary color used by the institution
logonullablestring
Base64 encoded representation of the institution's logo, returned as a base64 encoded 152x152 PNG. Not all institutions' logos are available.
routing_numbers[string]
A list of routing numbers known to be associated with the institution. This list is provided for the purpose of looking up institutions by routing number. It is generally comprehensive but is not guaranteed to be a complete list of routing numbers for an institution.
dtc_numbers[string]
A partial list of DTC numbers associated with the institution.
oauthboolean
Indicates that the institution has an OAuth login flow. This will be
true if OAuth is supported for any Items associated with the institution, even if the institution also supports non-OAuth connections.statusnullableobject
The status of an institution is determined by the health of its Item logins, Transactions updates, Investments updates, Liabilities updates, Auth requests, Balance requests, Identity requests, Investments requests, and Liabilities requests. A login attempt is conducted during the initial Item add in Link. If there is not enough traffic to accurately calculate an institution's status, Plaid will return null rather than potentially inaccurate data.
Institution status is accessible in the Dashboard and via the API using the
Institution status is accessible in the Dashboard and via the API using the
/institutions/get_by_id endpoint with the include_status option set to true. Note that institution status is not available in the Sandbox environment.item_loginsnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDtransactions_updatesnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDauthnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDidentitynullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDinvestments_updatesnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDliabilities_updatesnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDliabilitiesnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDinvestmentsnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDhealth_incidentsnullable[object]
Details of recent health incidents associated with the institution.
start_datestring
titlestring
The title of the incident
incident_updates[object]
Updates on the health incident.
descriptionstring
The content of the update.
statusstring
The status of the incident.
Possible values:
INVESTIGATING, IDENTIFIED, SCHEDULED, RESOLVED, UNKNOWNupdated_datestring
The date when the update was published, in ISO 8601 format, e.g.
"2020-10-30T15:26:48Z".Format:
date-time payment_initiationnullableobject
Metadata that captures what specific payment configurations an institution supports when making Payment Initiation requests.
supportsboolean
Indicates whether the institution supports payments from a different country.
supports_sepa_instantboolean
Indicates whether the institution supports SEPA Instant payments.
maximum_payment_amountobject
A mapping of currency to maximum payment amount (denominated in the smallest unit of currency) supported by the institution.
Example:
Example:
{"GBP": "10000"}supports_refundboolean
Indicates whether the institution supports returning refund details when initiating a payment.
standing_ordernullableobject
Metadata specifically related to valid Payment Initiation standing order configurations for the institution.
supports_standingboolean
Indicates whether the institution supports closed-ended standing orders by providing an end date.
supports_standingboolean
This is only applicable to
MONTHLY standing orders. Indicates whether the institution supports negative integers (-1 to -5) for setting up a MONTHLY standing order relative to the end of the month.valid_standing_order[string]
A list of the valid standing order intervals supported by the institution.
Possible values:
WEEKLY, MONTHLYMin length:
1 supports_paymentboolean
Indicates whether the institution supports payment consents.
auth_metadatanullableobject
Metadata that captures information about the Auth features of an institution.
supported_methodsnullableobject
Metadata specifically related to which auth methods an institution supports.
instant_authboolean
Indicates if instant auth is supported.
instant_matchboolean
Indicates if instant match is supported.
automated_microboolean
Indicates if automated microdeposits are supported.
instant_micro_depositsboolean
Indicates if instant microdeposits are supported.
totalinteger
The total number of institutions available via this endpoint
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{2 "institutions": [3 {4 "country_codes": [5 "US"6 ],7 "institution_id": "ins_1",8 "name": "Bank of America",9 "products": [10 "assets",11 "auth",12 "balance",13 "transactions",14 "identity",15 "liabilities"16 ],17 "routing_numbers": [18 "011000138",19 "011200365",20 "011400495"21 ],22 "dtc_numbers": [23 "2236",24 "0955",25 "1367"26 ],27 "oauth": false,28 "status": {29 "item_logins": {30 "status": "HEALTHY",31 "last_status_change": "2019-02-15T15:53:00Z",32 "breakdown": {33 "success": 0.9,34 "error_plaid": 0.01,35 "error_institution": 0.0936 }37 },38 "transactions_updates": {39 "status": "HEALTHY",40 "last_status_change": "2019-02-12T08:22:00Z",41 "breakdown": {42 "success": 0.95,43 "error_plaid": 0.02,44 "error_institution": 0.03,45 "refresh_interval": "NORMAL"46 }47 },48 "auth": {49 "status": "HEALTHY",50 "last_status_change": "2019-02-15T15:53:00Z",51 "breakdown": {52 "success": 0.91,53 "error_plaid": 0.01,54 "error_institution": 0.0855 }56 },57 "identity": {58 "status": "DEGRADED",59 "last_status_change": "2019-02-15T15:50:00Z",60 "breakdown": {61 "success": 0.42,62 "error_plaid": 0.08,63 "error_institution": 0.564 }65 },66 "investments": {67 "status": "HEALTHY",68 "last_status_change": "2019-02-15T15:53:00Z",69 "breakdown": {70 "success": 0.89,71 "error_plaid": 0.02,72 "error_institution": 0.0973 },74 "liabilities": {75 "status": "HEALTHY",76 "last_status_change": "2019-02-15T15:53:00Z",77 "breakdown": {78 "success": 0.89,79 "error_plaid": 0.02,80 "error_institution": 0.0981 }82 }83 },84 "investments_updates": {85 "status": "HEALTHY",86 "last_status_change": "2019-02-12T08:22:00Z",87 "breakdown": {88 "success": 0.95,89 "error_plaid": 0.02,90 "error_institution": 0.03,91 "refresh_interval": "NORMAL"92 }93 },94 "liabilities_updates": {95 "status": "HEALTHY",96 "last_status_change": "2019-02-12T08:22:00Z",97 "breakdown": {98 "success": 0.95,99 "error_plaid": 0.02,100 "error_institution": 0.03,101 "refresh_interval": "NORMAL"102 }103 }104 }105 }106 ],107 "request_id": "tbFyCEqkU774ZGG",108 "total": 11384109}/institutions/get_by_id
Get details of an institution
Returns a JSON response containing details on a specified financial institution currently supported by Plaid.
Versioning note: API versions 2019-05-29 and earlier allow use of the public_key parameter instead of the client_id and secret to authenticate to this endpoint. The public_key has been deprecated; all customers are encouraged to use client_id and secret instead.
Request fields
client_idstring
Your Plaid API
client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.secretstring
Your Plaid API
secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.institution_idrequiredstring
The ID of the institution to get details about
Min length:
1 country_codesrequired[string]
Specify which country or countries to include institutions from, using the ISO-3166-1 alpha-2 country code standard. In API versions 2019-05-29 and earlier, the
country_codes parameter is an optional parameter within the options object and will default to [US] if it is not supplied.Possible values:
US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT, BE, AT, FIoptionsobject
Specifies optional parameters for
/institutions/get_by_id. If provided, must not be null.include_optionalboolean
When
Note that Plaid does not own any of the logos shared by the API and that by accessing or using these logos, you agree that you are doing so at your own risk and will, if necessary, obtain all required permissions from the appropriate rights holders and adhere to any applicable usage guidelines. Plaid disclaims all express or implied warranties with respect to the logos.
true, return an institution's logo, brand color, and URL. When available, the bank's logo is returned as a base64 encoded 152x152 PNG, the brand color is in hexadecimal format. The default value is false.Note that Plaid does not own any of the logos shared by the API and that by accessing or using these logos, you agree that you are doing so at your own risk and will, if necessary, obtain all required permissions from the appropriate rights holders and adhere to any applicable usage guidelines. Plaid disclaims all express or implied warranties with respect to the logos.
Default:
false include_statusboolean
If
true, the response will include status information about the institution. Default value is false.Default:
false include_auth_metadataboolean
When
true, returns metadata related to the Auth product indicating which auth methods are supported.Default:
false include_paymentboolean
When
true, returns metadata related to the Payment Initiation product indicating which payment configurations are supported.Default:
false Select group for content switcher
1const request: InstitutionsGetByIdRequest = {2 institution_id: institutionID,3 country_codes: ['US'],4};5try {6 const response = await plaidClient.institutionsGetById(request);7 const institution = response.data.institution;8} catch (error) {9 // Handle error10}Response fields and example
institutionobject
Details relating to a specific financial institution
institution_idstring
Unique identifier for the institution. Note that the same institution may have multiple records, each with different institution IDs; for example, if the institution has migrated to OAuth, there may be separate
institution_ids for the OAuth and non-OAuth versions of the institution. Institutions that operate in different countries or with multiple login portals may also have separate institution_ids for each country or portal.namestring
The official name of the institution.
products[string]
A list of the Plaid products supported by the institution. Note that only institutions that support Instant Auth will return
auth in the product array; institutions that do not list auth may still support other Auth methods such as Instant Match or Automated Micro-deposit Verification. To identify institutions that support those methods, use the auth_metadata object. For more details, see Full Auth coverage. The income_verification product here indicates support for Bank Income.Possible values:
assets, auth, balance, balance_plus, beacon, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, standing_orders, transfer, employment, recurring_transactions, transactions_refresh, signal, statements, processor_payments, processor_identity, profile, cra_base_report, cra_income_insights, cra_partner_insights, cra_network_insights, cra_cashflow_insights, layer, pay_by_bank, protect_linked_bankcountry_codes[string]
A list of the country codes supported by the institution.
Possible values:
US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT, BE, AT, FIurlnullablestring
The URL for the institution's website
primary_colornullablestring
Hexadecimal representation of the primary color used by the institution
logonullablestring
Base64 encoded representation of the institution's logo, returned as a base64 encoded 152x152 PNG. Not all institutions' logos are available.
routing_numbers[string]
A list of routing numbers known to be associated with the institution. This list is provided for the purpose of looking up institutions by routing number. It is generally comprehensive but is not guaranteed to be a complete list of routing numbers for an institution.
dtc_numbers[string]
A partial list of DTC numbers associated with the institution.
oauthboolean
Indicates that the institution has an OAuth login flow. This will be
true if OAuth is supported for any Items associated with the institution, even if the institution also supports non-OAuth connections.statusnullableobject
The status of an institution is determined by the health of its Item logins, Transactions updates, Investments updates, Liabilities updates, Auth requests, Balance requests, Identity requests, Investments requests, and Liabilities requests. A login attempt is conducted during the initial Item add in Link. If there is not enough traffic to accurately calculate an institution's status, Plaid will return null rather than potentially inaccurate data.
Institution status is accessible in the Dashboard and via the API using the
Institution status is accessible in the Dashboard and via the API using the
/institutions/get_by_id endpoint with the include_status option set to true. Note that institution status is not available in the Sandbox environment.item_loginsnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDtransactions_updatesnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDauthnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDidentitynullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDinvestments_updatesnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDliabilities_updatesnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDliabilitiesnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDinvestmentsnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDhealth_incidentsnullable[object]
Details of recent health incidents associated with the institution.
start_datestring
titlestring
The title of the incident
incident_updates[object]
Updates on the health incident.
descriptionstring
The content of the update.
statusstring
The status of the incident.
Possible values:
INVESTIGATING, IDENTIFIED, SCHEDULED, RESOLVED, UNKNOWNupdated_datestring
The date when the update was published, in ISO 8601 format, e.g.
"2020-10-30T15:26:48Z".Format:
date-time payment_initiationnullableobject
Metadata that captures what specific payment configurations an institution supports when making Payment Initiation requests.
supportsboolean
Indicates whether the institution supports payments from a different country.
supports_sepa_instantboolean
Indicates whether the institution supports SEPA Instant payments.
maximum_payment_amountobject
A mapping of currency to maximum payment amount (denominated in the smallest unit of currency) supported by the institution.
Example:
Example:
{"GBP": "10000"}supports_refundboolean
Indicates whether the institution supports returning refund details when initiating a payment.
standing_ordernullableobject
Metadata specifically related to valid Payment Initiation standing order configurations for the institution.
supports_standingboolean
Indicates whether the institution supports closed-ended standing orders by providing an end date.
supports_standingboolean
This is only applicable to
MONTHLY standing orders. Indicates whether the institution supports negative integers (-1 to -5) for setting up a MONTHLY standing order relative to the end of the month.valid_standing_order[string]
A list of the valid standing order intervals supported by the institution.
Possible values:
WEEKLY, MONTHLYMin length:
1 supports_paymentboolean
Indicates whether the institution supports payment consents.
auth_metadatanullableobject
Metadata that captures information about the Auth features of an institution.
supported_methodsnullableobject
Metadata specifically related to which auth methods an institution supports.
instant_authboolean
Indicates if instant auth is supported.
instant_matchboolean
Indicates if instant match is supported.
automated_microboolean
Indicates if automated microdeposits are supported.
instant_micro_depositsboolean
Indicates if instant microdeposits are supported.
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{2 "institution": {3 "country_codes": [4 "US"5 ],6 "institution_id": "ins_109512",7 "name": "Houndstooth Bank",8 "products": [9 "auth",10 "balance",11 "identity",12 "transactions"13 ],14 "routing_numbers": [15 "011000138",16 "011200365",17 "011400495"18 ],19 "dtc_numbers": [20 "2236",21 "0955",22 "1367"23 ],24 "oauth": false,25 "status": {26 "item_logins": {27 "status": "HEALTHY",28 "last_status_change": "2019-02-15T15:53:00Z",29 "breakdown": {30 "success": 0.9,31 "error_plaid": 0.01,32 "error_institution": 0.0933 }34 },35 "transactions_updates": {36 "status": "HEALTHY",37 "last_status_change": "2019-02-12T08:22:00Z",38 "breakdown": {39 "success": 0.95,40 "error_plaid": 0.02,41 "error_institution": 0.03,42 "refresh_interval": "NORMAL"43 }44 },45 "auth": {46 "status": "HEALTHY",47 "last_status_change": "2019-02-15T15:53:00Z",48 "breakdown": {49 "success": 0.91,50 "error_plaid": 0.01,51 "error_institution": 0.0852 }53 },54 "identity": {55 "status": "DEGRADED",56 "last_status_change": "2019-02-15T15:50:00Z",57 "breakdown": {58 "success": 0.42,59 "error_plaid": 0.08,60 "error_institution": 0.561 }62 },63 "investments": {64 "status": "HEALTHY",65 "last_status_change": "2019-02-15T15:53:00Z",66 "breakdown": {67 "success": 0.89,68 "error_plaid": 0.02,69 "error_institution": 0.0970 },71 "liabilities": {72 "status": "HEALTHY",73 "last_status_change": "2019-02-15T15:53:00Z",74 "breakdown": {75 "success": 0.89,76 "error_plaid": 0.02,77 "error_institution": 0.0978 }79 }80 },81 "investments_updates": {82 "status": "HEALTHY",83 "last_status_change": "2019-02-12T08:22:00Z",84 "breakdown": {85 "success": 0.95,86 "error_plaid": 0.02,87 "error_institution": 0.03,88 "refresh_interval": "NORMAL"89 }90 },91 "liabilities_updates": {92 "status": "HEALTHY",93 "last_status_change": "2019-02-12T08:22:00Z",94 "breakdown": {95 "success": 0.95,96 "error_plaid": 0.02,97 "error_institution": 0.03,98 "refresh_interval": "NORMAL"99 }100 }101 },102 "primary_color": "#004966",103 "url": "https://plaid.com",104 "logo": null105 },106 "request_id": "m8MDnv9okwxFNBV"107}/institutions/search
Search institutions
Returns a JSON response containing details for institutions that match the query parameters, up to a maximum of ten institutions per query.
Versioning note: API versions 2019-05-29 and earlier allow use of the public_key parameter instead of the client_id and secret parameters to authenticate to this endpoint. The public_key parameter has since been deprecated; all customers are encouraged to use client_id and secret instead.
Request fields
client_idstring
Your Plaid API
client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.secretstring
Your Plaid API
secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.queryrequiredstring
The search query. Institutions with names matching the query are returned
Min length:
1 products[string]
Filter the Institutions based on whether they support all products listed in
products. Provide null to get institutions regardless of supported products. Note that when auth is specified as a product, if you are enabled for Instant Match or Automated Micro-deposits, institutions that support those products will be returned even if auth is not present in their product array.Min items:
1 Possible values:
assets, auth, balance, employment, identity, income_verification, investments, liabilities, identity_verification, payment_initiation, standing_orders, statements, transactions, transfercountry_codesrequired[string]
Specify which country or countries to include institutions from, using the ISO-3166-1 alpha-2 country code standard. In API versions 2019-05-29 and earlier, the
country_codes parameter is an optional parameter within the options object and will default to [US] if it is not supplied.Possible values:
US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT, BE, AT, FIoptionsobject
An optional object to filter
/institutions/search results.oauthboolean
Limit results to institutions with or without OAuth login flows. Note that institutions will have
oauth set to true if some Items associated with that institution are required to use OAuth flows; institutions in a state of migration to OAuth will have the oauth attribute set to true.include_optionalboolean
When true, return the institution's homepage URL, logo and primary brand color.
include_auth_metadataboolean
When
true, returns metadata related to the Auth product indicating which auth methods are supported.Default:
false include_paymentboolean
When
true, returns metadata related to the Payment Initiation product indicating which payment configurations are supported.Default:
false payment_initiationobject
Additional options that will be used to filter institutions by various Payment Initiation configurations.
payment_idstring
A unique ID identifying the payment
consent_idstring
A unique ID identifying the payment consent
Select group for content switcher
1const request: InstitutionsSearchRequest = {2 query: institutionID,3 products: ['transactions'],4 country_codes: ['US'],5};6try {7 const response = await plaidClient.institutionsSearch(request);8 const institutions = response.data.institutions;9} catch (error) {10 // Handle error11}Response fields and example
institutions[object]
An array of institutions matching the search criteria
institution_idstring
Unique identifier for the institution. Note that the same institution may have multiple records, each with different institution IDs; for example, if the institution has migrated to OAuth, there may be separate
institution_ids for the OAuth and non-OAuth versions of the institution. Institutions that operate in different countries or with multiple login portals may also have separate institution_ids for each country or portal.namestring
The official name of the institution.
products[string]
A list of the Plaid products supported by the institution. Note that only institutions that support Instant Auth will return
auth in the product array; institutions that do not list auth may still support other Auth methods such as Instant Match or Automated Micro-deposit Verification. To identify institutions that support those methods, use the auth_metadata object. For more details, see Full Auth coverage. The income_verification product here indicates support for Bank Income.Possible values:
assets, auth, balance, balance_plus, beacon, identity, identity_match, investments, investments_auth, liabilities, payment_initiation, identity_verification, transactions, credit_details, income, income_verification, standing_orders, transfer, employment, recurring_transactions, transactions_refresh, signal, statements, processor_payments, processor_identity, profile, cra_base_report, cra_income_insights, cra_partner_insights, cra_network_insights, cra_cashflow_insights, layer, pay_by_bank, protect_linked_bankcountry_codes[string]
A list of the country codes supported by the institution.
Possible values:
US, GB, ES, NL, FR, IE, CA, DE, IT, PL, DK, NO, SE, EE, LT, LV, PT, BE, AT, FIurlnullablestring
The URL for the institution's website
primary_colornullablestring
Hexadecimal representation of the primary color used by the institution
logonullablestring
Base64 encoded representation of the institution's logo, returned as a base64 encoded 152x152 PNG. Not all institutions' logos are available.
routing_numbers[string]
A list of routing numbers known to be associated with the institution. This list is provided for the purpose of looking up institutions by routing number. It is generally comprehensive but is not guaranteed to be a complete list of routing numbers for an institution.
dtc_numbers[string]
A partial list of DTC numbers associated with the institution.
oauthboolean
Indicates that the institution has an OAuth login flow. This will be
true if OAuth is supported for any Items associated with the institution, even if the institution also supports non-OAuth connections.statusnullableobject
The status of an institution is determined by the health of its Item logins, Transactions updates, Investments updates, Liabilities updates, Auth requests, Balance requests, Identity requests, Investments requests, and Liabilities requests. A login attempt is conducted during the initial Item add in Link. If there is not enough traffic to accurately calculate an institution's status, Plaid will return null rather than potentially inaccurate data.
Institution status is accessible in the Dashboard and via the API using the
Institution status is accessible in the Dashboard and via the API using the
/institutions/get_by_id endpoint with the include_status option set to true. Note that institution status is not available in the Sandbox environment.item_loginsnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDtransactions_updatesnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDauthnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDidentitynullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDinvestments_updatesnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDliabilities_updatesnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDliabilitiesnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDinvestmentsnullableobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object.
statusdeprecatedstring
This field is deprecated in favor of the
breakdown object, which provides more granular institution health data.HEALTHY: the majority of requests are successful
DEGRADED: only some requests are successful
DOWN: all requests are failingPossible values:
HEALTHY, DEGRADED, DOWNlast_status_changestring
breakdownobject
A detailed breakdown of the institution's performance for a request type. The values for
success, error_plaid, and error_institution sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see Institution status details.successnumber
The percentage of login attempts that are successful, expressed as a decimal.
Format:
double error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
Format:
double error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
Format:
double refresh_intervalstring
How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The
refresh_interval may be DELAYED or STOPPED even when the success rate is high.Possible values:
NORMAL, DELAYED, STOPPEDhealth_incidentsnullable[object]
Details of recent health incidents associated with the institution.
start_datestring
titlestring
The title of the incident
incident_updates[object]
Updates on the health incident.
descriptionstring
The content of the update.
statusstring
The status of the incident.
Possible values:
INVESTIGATING, IDENTIFIED, SCHEDULED, RESOLVED, UNKNOWNupdated_datestring
The date when the update was published, in ISO 8601 format, e.g.
"2020-10-30T15:26:48Z".Format:
date-time payment_initiationnullableobject
Metadata that captures what specific payment configurations an institution supports when making Payment Initiation requests.
supportsboolean
Indicates whether the institution supports payments from a different country.
supports_sepa_instantboolean
Indicates whether the institution supports SEPA Instant payments.
maximum_payment_amountobject
A mapping of currency to maximum payment amount (denominated in the smallest unit of currency) supported by the institution.
Example:
Example:
{"GBP": "10000"}supports_refundboolean
Indicates whether the institution supports returning refund details when initiating a payment.
standing_ordernullableobject
Metadata specifically related to valid Payment Initiation standing order configurations for the institution.
supports_standingboolean
Indicates whether the institution supports closed-ended standing orders by providing an end date.
supports_standingboolean
This is only applicable to
MONTHLY standing orders. Indicates whether the institution supports negative integers (-1 to -5) for setting up a MONTHLY standing order relative to the end of the month.valid_standing_order[string]
A list of the valid standing order intervals supported by the institution.
Possible values:
WEEKLY, MONTHLYMin length:
1 supports_paymentboolean
Indicates whether the institution supports payment consents.
auth_metadatanullableobject
Metadata that captures information about the Auth features of an institution.
supported_methodsnullableobject
Metadata specifically related to which auth methods an institution supports.
instant_authboolean
Indicates if instant auth is supported.
instant_matchboolean
Indicates if instant match is supported.
automated_microboolean
Indicates if automated microdeposits are supported.
instant_micro_depositsboolean
Indicates if instant microdeposits are supported.
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{2 "institutions": [3 {4 "country_codes": [5 "US"6 ],7 "institution_id": "ins_118923",8 "name": "Red Platypus Bank - Red Platypus Bank",9 "products": [10 "assets",11 "auth",12 "balance",13 "transactions",14 "identity"15 ],16 "routing_numbers": [17 "011000138",18 "011200365",19 "011400495"20 ],21 "dtc_numbers": [22 "2236",23 "0955",24 "1367"25 ],26 "oauth": false,27 "status": {28 "item_logins": {29 "status": "HEALTHY",30 "last_status_change": "2019-02-15T15:53:00Z",31 "breakdown": {32 "success": 0.9,33 "error_plaid": 0.01,34 "error_institution": 0.0935 }36 },37 "transactions_updates": {38 "status": "HEALTHY",39 "last_status_change": "2019-02-12T08:22:00Z",40 "breakdown": {41 "success": 0.95,42 "error_plaid": 0.02,43 "error_institution": 0.03,44 "refresh_interval": "NORMAL"45 }46 },47 "auth": {48 "status": "HEALTHY",49 "last_status_change": "2019-02-15T15:53:00Z",50 "breakdown": {51 "success": 0.91,52 "error_plaid": 0.01,53 "error_institution": 0.0854 }55 },56 "identity": {57 "status": "DEGRADED",58 "last_status_change": "2019-02-15T15:50:00Z",59 "breakdown": {60 "success": 0.42,61 "error_plaid": 0.08,62 "error_institution": 0.563 }64 },65 "investments": {66 "status": "HEALTHY",67 "last_status_change": "2019-02-15T15:53:00Z",68 "breakdown": {69 "success": 0.89,70 "error_plaid": 0.02,71 "error_institution": 0.0972 },73 "liabilities": {74 "status": "HEALTHY",75 "last_status_change": "2019-02-15T15:53:00Z",76 "breakdown": {77 "success": 0.89,78 "error_plaid": 0.02,79 "error_institution": 0.0980 }81 }82 },83 "investments_updates": {84 "status": "HEALTHY",85 "last_status_change": "2019-02-12T08:22:00Z",86 "breakdown": {87 "success": 0.95,88 "error_plaid": 0.02,89 "error_institution": 0.03,90 "refresh_interval": "NORMAL"91 }92 },93 "liabilities_updates": {94 "status": "HEALTHY",95 "last_status_change": "2019-02-12T08:22:00Z",96 "breakdown": {97 "success": 0.95,98 "error_plaid": 0.02,99 "error_institution": 0.03,100 "refresh_interval": "NORMAL"101 }102 }103 }104 }105 ],106 "request_id": "Ggmk0enW4smO2Tp"107}Webhooks
Institution status alerts are configured within the developer dashboard. In the dashboard, you can choose to receive alerts as either emails or webhooks.
All dashboard-configured institution status alerts will have type DASHBOARD_CONFIGURED_ALERT.
INSTITUTION_STATUS_ALERT_TRIGGERED
Fired when institution status meets the conditions configured in the developer dashboard.
Properties
webhook_typestring
DASHBOARD_CONFIGURED_ALERTwebhook_codestring
INSTITUTION_STATUS_ALERT_TRIGGEREDinstitution_idstring
The ID of the associated institution.
institution_overallnumber
The global success rate of the institution, calculated based on item add health.
Format:
double environmentstring
The Plaid environment the webhook was sent from
Possible values:
sandbox, production1{2 "webhook_type": "DASHBOARD_CONFIGURED_ALERT",3 "webhook_code": "INSTITUTION_STATUS_ALERT_TRIGGERED",4 "institution_id": "ins_3",5 "institution_overall_success_rate": 0.9,6 "environment": "production"7}