Search institutions

POST /institutions/search

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 Body

Required

InstitutionsSearchRequest defines the request schema for /institutions/search

Parameters

client_id
string
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.
secret
string
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.
query
required, string
The search query. Institutions with names matching the query are returned
products
array[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.
country_codes
required, array[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.
options
object
An optional object to filter /institutions/search results.
oauth
boolean
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_optional_metadata
boolean
When true, return the institution’s homepage URL, logo and primary brand color.
include_auth_metadata
boolean
When true, returns metadata related to the Auth product indicating which auth methods are supported.
include_payment_initiation_metadata
boolean
When true, returns metadata related to the Payment Initiation product indicating which payment configurations are supported.
payment_initiation
object
Additional options that will be used to filter institutions by various Payment Initiation configurations.
payment_id
string
A unique ID identifying the payment
consent_id
string
A unique ID identifying the payment consent

Response

InstitutionsSearchResponse defines the response schema for /institutions/search

Response Properties

institutions
required, array[object]
An array of institutions matching the search criteria
institution_id
required, string
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.
name
required, string
The official name of the institution.
products
required, array[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.
country_codes
required, array[string]
A list of the country codes supported by the institution.
url
string
The URL for the institution’s website
primary_color
string
Hexadecimal representation of the primary color used by the institution
logo
string
Base64 encoded representation of the institution’s logo, returned as a base64 encoded 152x152 PNG. Not all institutions’ logos are available.
routing_numbers
required, array[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
array[string]
A partial list of DTC numbers associated with the institution.
oauth
required, boolean
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.
status
object
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 /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_logins
object
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.
status
required, string
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 failing
last_status_change
required, string
ISO 8601 formatted timestamp of the last status change for the institution.
breakdown
required, object
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.
success
required, number
The percentage of login attempts that are successful, expressed as a decimal.
error_plaid
required, number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institution
required, number
The percentage of logins that are failing due to an issue in the institution’s system, expressed as a decimal.
refresh_interval
string
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.
transactions_updates
object
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.
status
required, string
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 failing
last_status_change
required, string
ISO 8601 formatted timestamp of the last status change for the institution.
breakdown
required, object
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.
success
required, number
The percentage of login attempts that are successful, expressed as a decimal.
error_plaid
required, number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institution
required, number
The percentage of logins that are failing due to an issue in the institution’s system, expressed as a decimal.
refresh_interval
string
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.
auth
object
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.
status
required, string
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 failing
last_status_change
required, string
ISO 8601 formatted timestamp of the last status change for the institution.
breakdown
required, object
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.
success
required, number
The percentage of login attempts that are successful, expressed as a decimal.
error_plaid
required, number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institution
required, number
The percentage of logins that are failing due to an issue in the institution’s system, expressed as a decimal.
refresh_interval
string
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.
identity
object
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.
status
required, string
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 failing
last_status_change
required, string
ISO 8601 formatted timestamp of the last status change for the institution.
breakdown
required, object
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.
success
required, number
The percentage of login attempts that are successful, expressed as a decimal.
error_plaid
required, number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institution
required, number
The percentage of logins that are failing due to an issue in the institution’s system, expressed as a decimal.
refresh_interval
string
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.
investments_updates
object
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.
status
required, string
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 failing
last_status_change
required, string
ISO 8601 formatted timestamp of the last status change for the institution.
breakdown
required, object
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.
success
required, number
The percentage of login attempts that are successful, expressed as a decimal.
error_plaid
required, number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institution
required, number
The percentage of logins that are failing due to an issue in the institution’s system, expressed as a decimal.
refresh_interval
string
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.
liabilities_updates
object
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.
status
required, string
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 failing
last_status_change
required, string
ISO 8601 formatted timestamp of the last status change for the institution.
breakdown
required, object
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.
success
required, number
The percentage of login attempts that are successful, expressed as a decimal.
error_plaid
required, number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institution
required, number
The percentage of logins that are failing due to an issue in the institution’s system, expressed as a decimal.
refresh_interval
string
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.
liabilities
object
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.
status
required, string
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 failing
last_status_change
required, string
ISO 8601 formatted timestamp of the last status change for the institution.
breakdown
required, object
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.
success
required, number
The percentage of login attempts that are successful, expressed as a decimal.
error_plaid
required, number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institution
required, number
The percentage of logins that are failing due to an issue in the institution’s system, expressed as a decimal.
refresh_interval
string
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.
investments
object
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.
status
required, string
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 failing
last_status_change
required, string
ISO 8601 formatted timestamp of the last status change for the institution.
breakdown
required, object
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.
success
required, number
The percentage of login attempts that are successful, expressed as a decimal.
error_plaid
required, number
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institution
required, number
The percentage of logins that are failing due to an issue in the institution’s system, expressed as a decimal.
refresh_interval
string
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.
health_incidents
array[object]
Details of recent health incidents associated with the institution.
start_date
required, string
The start date of the incident, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".
end_date
string
The end date of the incident, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".
title
required, string
The title of the incident
incident_updates
required, array[object]
Updates on the health incident.
description
string
The content of the update.
status
string
The status of the incident.
updated_date
string
The date when the update was published, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".
payment_initiation_metadata
object
Metadata that captures what specific payment configurations an institution supports when making Payment Initiation requests.
supports_international_payments
required, boolean
Indicates whether the institution supports payments from a different country.
supports_sepa_instant
required, boolean
Indicates whether the institution supports SEPA Instant payments.
maximum_payment_amount
required, object
A mapping of currency to maximum payment amount (denominated in the smallest unit of currency) supported by the institution. Example: {"GBP": "10000"}
supports_refund_details
required, boolean
Indicates whether the institution supports returning refund details when initiating a payment.
standing_order_metadata
required, object
Metadata specifically related to valid Payment Initiation standing order configurations for the institution.
supports_standing_order_end_date
required, boolean
Indicates whether the institution supports closed-ended standing orders by providing an end date.
supports_standing_order_negative_execution_days
required, boolean
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_intervals
required, array[string]
A list of the valid standing order intervals supported by the institution.
supports_payment_consents
required, boolean
Indicates whether the institution supports payment consents.
auth_metadata
object
Metadata that captures information about the Auth features of an institution.
supported_methods
required, object
Metadata specifically related to which auth methods an institution supports.
instant_auth
required, boolean
Indicates if instant auth is supported.
instant_match
required, boolean
Indicates if instant match is supported.
automated_micro_deposits
required, boolean
Indicates if automated microdeposits are supported.
instant_micro_deposits
required, boolean
Indicates if instant microdeposits are supported.
request_id
required, string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.