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 Help Center.
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.
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.count
1
500
offset
0
country_codes
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.1
US
, GB
, ES
, NL
, FR
, IE
, CA
, DE
, IT
, PL
, DK
, NO
, SE
, EE
, LT
, LV
, PT
, BE
options
/institutions/get
results.products
auth
, an institution must support Instant Auth to match the criterion.1
assets
, auth
, balance
, employment
, identity
, income_verification
, identity_verification
, investments
, liabilities
, payment_initiation
, standing_orders
, transactions
, transfer
routing_numbers
oauth
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
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_metadata
true
, returns metadata related to the Auth product indicating which auth methods are supported.false
include_payment _initiation_metadata
true
, returns metadata related to the Payment Initiation product indicating which payment configurations are supported.false
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
institution_id
institution_id
s 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_id
s for each country or portal.name
products
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.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
, 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
country_codes
US
, GB
, ES
, NL
, FR
, IE
, CA
, DE
, IT
, PL
, DK
, NO
, SE
, EE
, LT
, LV
, PT
, BE
url
primary_color
logo
routing_numbers
dtc_numbers
oauth
true
if OAuth is supported for any Items associated with the institution, even if the institution also supports non-OAuth connections.status
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
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
transactions_updates
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
auth
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
identity
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
investments_updates
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
liabilities_updates
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
liabilities
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
investments
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
health_incidents
start_date
title
incident_updates
description
status
INVESTIGATING
, IDENTIFIED
, SCHEDULED
, RESOLVED
, UNKNOWN
updated_date
"2020-10-30T15:26:48Z"
.date-time
payment_initiation _metadata
supports _international _payments
supports_sepa_instant
maximum_payment_amount
Example:
{"GBP": "10000"}
supports_refund _details
standing_order _metadata
supports_standing _order_end_date
supports_standing _order_negative _execution_days
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
WEEKLY
, MONTHLY
1
supports_payment _consents
auth_metadata
supported_methods
instant_auth
instant_match
automated_micro _deposits
instant_micro_deposits
total
request_id
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}
Was this helpful?
/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.
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.institution_id
1
country_codes
country_codes
parameter is an optional parameter within the options
object and will default to [US]
if it is not supplied.US
, GB
, ES
, NL
, FR
, IE
, CA
, DE
, IT
, PL
, DK
, NO
, SE
, EE
, LT
, LV
, PT
, BE
options
/institutions/get_by_id
. If provided, must not be null
.include_optional _metadata
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.
false
include_status
true
, the response will include status information about the institution. Default value is false
.false
include_auth_metadata
true
, returns metadata related to the Auth product indicating which auth methods are supported.false
include_payment _initiation_metadata
true
, returns metadata related to the Payment Initiation product indicating which payment configurations are supported.false
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
institution
institution_id
institution_id
s 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_id
s for each country or portal.name
products
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.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
, 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
country_codes
US
, GB
, ES
, NL
, FR
, IE
, CA
, DE
, IT
, PL
, DK
, NO
, SE
, EE
, LT
, LV
, PT
, BE
url
primary_color
logo
routing_numbers
dtc_numbers
oauth
true
if OAuth is supported for any Items associated with the institution, even if the institution also supports non-OAuth connections.status
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
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
transactions_updates
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
auth
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
identity
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
investments_updates
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
liabilities_updates
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
liabilities
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
investments
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
health_incidents
start_date
title
incident_updates
description
status
INVESTIGATING
, IDENTIFIED
, SCHEDULED
, RESOLVED
, UNKNOWN
updated_date
"2020-10-30T15:26:48Z"
.date-time
payment_initiation _metadata
supports _international _payments
supports_sepa_instant
maximum_payment_amount
Example:
{"GBP": "10000"}
supports_refund _details
standing_order _metadata
supports_standing _order_end_date
supports_standing _order_negative _execution_days
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
WEEKLY
, MONTHLY
1
supports_payment _consents
auth_metadata
supported_methods
instant_auth
instant_match
automated_micro _deposits
instant_micro_deposits
request_id
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}
Was this helpful?
/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.
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.query
1
products
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.1
assets
, auth
, balance
, employment
, identity
, income_verification
, investments
, liabilities
, identity_verification
, payment_initiation
, standing_orders
, statements
, transactions
, transfer
country_codes
country_codes
parameter is an optional parameter within the options
object and will default to [US]
if it is not supplied.US
, GB
, ES
, NL
, FR
, IE
, CA
, DE
, IT
, PL
, DK
, NO
, SE
, EE
, LT
, LV
, PT
, BE
options
/institutions/search
results.oauth
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
include_auth_metadata
true
, returns metadata related to the Auth product indicating which auth methods are supported.false
include_payment _initiation_metadata
true
, returns metadata related to the Payment Initiation product indicating which payment configurations are supported.false
payment_initiation
payment_id
consent_id
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
institution_id
institution_id
s 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_id
s for each country or portal.name
products
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.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
, 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
country_codes
US
, GB
, ES
, NL
, FR
, IE
, CA
, DE
, IT
, PL
, DK
, NO
, SE
, EE
, LT
, LV
, PT
, BE
url
primary_color
logo
routing_numbers
dtc_numbers
oauth
true
if OAuth is supported for any Items associated with the institution, even if the institution also supports non-OAuth connections.status
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
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
transactions_updates
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
auth
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
identity
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
investments_updates
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
liabilities_updates
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
liabilities
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
investments
status
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 failingHEALTHY
, DEGRADED
, DOWN
last_status_change
breakdown
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
double
error_plaid
double
error_institution
double
refresh_interval
refresh_interval
may be DELAYED
or STOPPED
even when the success rate is high.NORMAL
, DELAYED
, STOPPED
health_incidents
start_date
title
incident_updates
description
status
INVESTIGATING
, IDENTIFIED
, SCHEDULED
, RESOLVED
, UNKNOWN
updated_date
"2020-10-30T15:26:48Z"
.date-time
payment_initiation _metadata
supports _international _payments
supports_sepa_instant
maximum_payment_amount
Example:
{"GBP": "10000"}
supports_refund _details
standing_order _metadata
supports_standing _order_end_date
supports_standing _order_negative _execution_days
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
WEEKLY
, MONTHLY
1
supports_payment _consents
auth_metadata
supported_methods
instant_auth
instant_match
automated_micro _deposits
instant_micro_deposits
request_id
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}
Was this helpful?
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.
webhook_type
DASHBOARD_CONFIGURED_ALERT
webhook_code
INSTITUTION_STATUS_ALERT_TRIGGERED
institution_id
institution_overall _success_rate
double
environment
sandbox
, production
1{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}