Institutions endpoints

Fetch data about supported institutions

The interface for these endpoints has changed in a recent API release. If you are using an API version prior to 2020-09-14, make sure to select the version you are using from the API dropdown at the top of the page. For more information, 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. 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.

Plaid supports over 11,500 institutions across North America and Europe. Supported countries are:

  • United States (US)
  • Canada (CA)
  • United Kingdom (GB)
  • Ireland (IE)
  • France (FR)
  • Spain (ES)
  • Netherlands (NL)

By default, you receive access to institutions in all countries in Sandbox and Development, and to United States and Canada in Production. To gain access to additional countries in Production, file a product access Support ticket.

/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.
This data changes frequently. If you store it locally on your system, be sure to update it regularly.

institutions/get

Request fields and example

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.
Maximum: 500
offsetrequiredinteger
The number of Institutions to skip.
country_codesrequired[string]
Specify an array of Plaid-supported country codes this institution supports, using the ISO-3166-1 alpha-2 country code standard.
Min items: 1
Possible values: US, GB, ES, NL, FR, IE, CA
optionsobject
An optional object to filter /institutions/get results.
products[string]
Filter the Institutions based on which products they support.
Possible values: assets, auth, balance, identity, investments, liabilities, payment_initiation, transactions, credit_details, income, deposit_switch, standing_orders
routing_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.
oauthboolean
Limit results to institutions with or without OAuth login flows. This is primarily relevant to institutions with European country codes.
include_optional_metadataboolean
When true, return the institution's homepage URL, logo and primary brand color.
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_payment_initiation_metadataboolean
When true, returns metadata related to the Payment Initiation product indicating which payment configurations are supported.
Default: false
1
2
3
4
5
// Pull institutions
client.getInstitutions(count, offset, countryCodes, (err, result) => {
  // Handle err
  const institutions = result.institutions;
});
institutions/get

Response fields and example

institutions[object]
A list of Plaid Institution
institution_idstring
Unique identifier for the institution
namestring
The official name of the institution
products[string]
A list of the Plaid products supported by the institution
Possible values: assets, auth, balance, identity, investments, liabilities, payment_initiation, transactions, credit_details, income, deposit_switch, standing_orders
country_codes[string]
A list of the country codes supported by the institution.
Possible values: US, GB, ES, NL, FR, IE, CA
urlnullablestring
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
routing_numbersnullable[string]
A partial list of routing numbers associated with the institution. This list is provided for the purpose of looking up institutions by routing number. It is not comprehensive and should never be used as a complete list of routing numbers for an institution.
oauthboolean
Indicates that the institution has an OAuth login flow. This is primarily relevant to institutions with European country codes.
statusobject
The status of an institution is determined by the health of its Item logins, Transactions updates, Investments updates, Auth requests, Balance requests, and Identity 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_loginsobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
transactions_updatesobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
authobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
balanceobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
identityobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
investments_updatesobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
health_incidentsnullable[object]
Details of recent health incidents associated with the institution.
start_datenullablestring
The start date of the incident, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".
end_datenullablestring
The end date of the incident, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".
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, RESOLVED, UNKNOWN
updated_datestring
The date when the update was published, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".
payment_initiation_metadatanullableobject
Metadata that captures what specific payment configurations an institution supports when making Payment Initiation requests.
supports_international_paymentsboolean
Indicates whether the institution supports payments from a different country.
maximum_payment_amountobject
A mapping of currency to maximum payment amount (denominated in the smallest unit of currency) supported by the insitution.
Example: {"GBP": "10000"}
supports_refund_detailsboolean
Indicates whether the institution supports returning refund details when initiating a payment.
standing_order_metadatanullableobject
Metadata specifically related to valid Payment Initiation standing order configurations for the institution.
supports_standing_order_end_dateboolean
Indicates whether the institution supports closed-ended standing orders by providing an end date.
supports_standing_order_negative_execution_daysboolean
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[string]
A list of the valid standing order intervals supported by the institution.
Possible values: WEEKLY, MONTHLY
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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
  "institutions": [
    {
      "country_codes": [
        "US"
      ],
      "institution_id": "ins_1",
      "name": "Bank of America",
      "oauth": false,
      "products": [
        "assets",
        "auth",
        "balance",
        "transactions",
        "identity",
        "liabilities"
      ],
      "routing_numbers": [
        "011000138",
        "011200365",
        "011400495",
        "011500010",
        "011900254",
        "021000322",
        "021200339",
        "026009593",
        "031202084",
        "051000017",
        "052001633",
        "053000196",
        "053904483",
        "054001204",
        "061000052",
        "063100277",
        "064000020",
        "071214579",
        "072000805",
        "073000176",
        "081000032",
        "081904808",
        "082000073",
        "101100045",
        "103000017",
        "107000327",
        "111000025",
        "121000358",
        "122101706",
        "122400724",
        "123103716",
        "125000024",
        "323070380"
      ]
    }
  ],
  "request_id": "tbFyCEqkU774ZGG",
  "total": 11384
}

/institutions/get_by_id

Get details of an institution

Returns a JSON response containing details on a specified financial institution currently supported by Plaid.

institutions/get_by_id

Request fields and example

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
country_codesrequired[string]
Specify an array of Plaid-supported country codes this institution supports, using the ISO-3166-1 alpha-2 country code standard.
Possible values: US, GB, ES, NL, FR, IE, CA
optionsobject
Specifies optional parameters for /institutions/get_by_id. If provided, must not be null.
include_optional_metadataboolean
When 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_payment_initiation_metadataboolean
When true, returns metadata related to the Payment Initiation product indicating which payment configurations are supported.
Default: false
1
2
3
4
client.getInstitutionById(institutionId, countryCodes, (err, result) => {
  // Handle err
  const institution = result.institution;
});
institutions/get_by_id

Response fields and example

institutionobject
Details relating to a specific financial institution
institution_idstring
Unique identifier for the institution
namestring
The official name of the institution
products[string]
A list of the Plaid products supported by the institution
Possible values: assets, auth, balance, identity, investments, liabilities, payment_initiation, transactions, credit_details, income, deposit_switch, standing_orders
country_codes[string]
A list of the country codes supported by the institution.
Possible values: US, GB, ES, NL, FR, IE, CA
urlnullablestring
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
routing_numbersnullable[string]
A partial list of routing numbers associated with the institution. This list is provided for the purpose of looking up institutions by routing number. It is not comprehensive and should never be used as a complete list of routing numbers for an institution.
oauthboolean
Indicates that the institution has an OAuth login flow. This is primarily relevant to institutions with European country codes.
statusobject
The status of an institution is determined by the health of its Item logins, Transactions updates, Investments updates, Auth requests, Balance requests, and Identity 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_loginsobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
transactions_updatesobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
authobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
balanceobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
identityobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
investments_updatesobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
health_incidentsnullable[object]
Details of recent health incidents associated with the institution.
start_datenullablestring
The start date of the incident, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".
end_datenullablestring
The end date of the incident, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".
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, RESOLVED, UNKNOWN
updated_datestring
The date when the update was published, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".
payment_initiation_metadatanullableobject
Metadata that captures what specific payment configurations an institution supports when making Payment Initiation requests.
supports_international_paymentsboolean
Indicates whether the institution supports payments from a different country.
maximum_payment_amountobject
A mapping of currency to maximum payment amount (denominated in the smallest unit of currency) supported by the insitution.
Example: {"GBP": "10000"}
supports_refund_detailsboolean
Indicates whether the institution supports returning refund details when initiating a payment.
standing_order_metadatanullableobject
Metadata specifically related to valid Payment Initiation standing order configurations for the institution.
supports_standing_order_end_dateboolean
Indicates whether the institution supports closed-ended standing orders by providing an end date.
supports_standing_order_negative_execution_daysboolean
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[string]
A list of the valid standing order intervals supported by the institution.
Possible values: WEEKLY, MONTHLY
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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
{
  "institution": {
    "country_codes": [
      "US"
    ],
    "institution_id": "ins_109512",
    "name": "Houndstooth Bank",
    "products": [
      "auth",
      "balance",
      "identity",
      "transactions"
    ],
    "routing_numbers": [
      "110000000"
    ],
    "oauth": false,
    "status": {
      "item_logins": {
        "status": "HEALTHY",
        "last_status_change": "2019-02-15T15:53:00Z",
        "breakdown": {
          "success": 0.9,
          "error_plaid": 0.01,
          "error_institution": 0.09
        }
      },
      "transactions_updates": {
        "status": "HEALTHY",
        "last_status_change": "2019-02-12T08:22:00Z",
        "breakdown": {
          "success": 0.95,
          "error_plaid": 0.02,
          "error_institution": 0.03,
          "refresh_interval": "NORMAL"
        }
      },
      "auth": {
        "status": "HEALTHY",
        "last_status_change": "2019-02-15T15:53:00Z",
        "breakdown": {
          "success": 0.91,
          "error_plaid": 0.01,
          "error_institution": 0.08
        }
      },
      "balance": {
        "status": "HEALTHY",
        "last_status_change": "2019-02-15T15:53:00Z",
        "breakdown": {
          "success": 0.89,
          "error_plaid": 0.02,
          "error_institution": 0.09
        }
      },
      "identity": {
        "status": "DEGRADED",
        "last_status_change": "2019-02-15T15:50:00Z",
        "breakdown": {
          "success": 0.42,
          "error_plaid": 0.08,
          "error_institution": 0.5
        }
      },
      "investments_updates": {
        "status": "HEALTHY",
        "last_status_change": "2019-02-12T08:22:00Z",
        "breakdown": {
          "success": 0.95,
          "error_plaid": 0.02,
          "error_institution": 0.03,
          "refresh_interval": "NORMAL"
        }
      },
      "primary_color": "#004966",
      "url": "https://plaid.com",
      "logo": null
    }
  },
  "request_id": "m8MDnv9okwxFNBV"
}

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

institutions/search

Request fields and example

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
productsrequired[string]
Filter the Institutions based on whether they support all products listed in products. Provide null to get institutions regardless of supported products
Min items: 1
Possible values: assets, auth, balance, identity, investments, liabilities, payment_initiation, transactions, credit_details, income, deposit_switch, standing_orders
country_codesrequired[string]
Specify an array of Plaid-supported country codes this institution supports, using the ISO-3166-1 alpha-2 country code standard.
Possible values: US, GB, ES, NL, FR, IE, CA
optionsobject
An optional object to filter /institutions/search results.
oauthboolean
Limit results to institutions with or without OAuth login flows. This is primarily relevant to institutions with European country codes
include_optional_metadataboolean
When true, return the institution's homepage URL, logo and primary brand color.
include_payment_initiation_metadataboolean
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
1
2
3
4
5
6
7
8
9
client.searchInstitutionsByName(
  SEARCH_QUERY,
  ['transactions'],
  countryCodes,
  (err, response) => {
    // Handle err
    const institutions = response.institutions;
  },
);
institutions/search

Response fields and example

institutions[object]
An array of institutions matching the search criteria
institution_idstring
Unique identifier for the institution
namestring
The official name of the institution
products[string]
A list of the Plaid products supported by the institution
Possible values: assets, auth, balance, identity, investments, liabilities, payment_initiation, transactions, credit_details, income, deposit_switch, standing_orders
country_codes[string]
A list of the country codes supported by the institution.
Possible values: US, GB, ES, NL, FR, IE, CA
urlnullablestring
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
routing_numbersnullable[string]
A partial list of routing numbers associated with the institution. This list is provided for the purpose of looking up institutions by routing number. It is not comprehensive and should never be used as a complete list of routing numbers for an institution.
oauthboolean
Indicates that the institution has an OAuth login flow. This is primarily relevant to institutions with European country codes.
statusobject
The status of an institution is determined by the health of its Item logins, Transactions updates, Investments updates, Auth requests, Balance requests, and Identity 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_loginsobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
transactions_updatesobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
authobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
balanceobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
identityobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
investments_updatesobject
A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Transactions updates, Investments updates, and Item logins each have their own status object.
statusstring
HEALTHY: the majority of requests are successful DEGRADED: only some requests are successful DOWN: all requests are failing
Possible values: HEALTHY, DEGRADED, DOWN
last_status_changestring
ISO 8601 formatted timestamp of the last status change for the institution.
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.
successnumber
The percentage of login attempts that are successful, expressed as a decimal.
error_plaidnumber
The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal.
error_institutionnumber
The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal.
refresh_intervalnullablestring
The refresh_interval may be DELAYED or STOPPED even when the success rate is high. This value is only returned for Transactions status breakdowns.
Possible values: NORMAL, DELAYED, STOPPED
health_incidentsnullable[object]
Details of recent health incidents associated with the institution.
start_datenullablestring
The start date of the incident, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".
end_datenullablestring
The end date of the incident, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".
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, RESOLVED, UNKNOWN
updated_datestring
The date when the update was published, in ISO 8601 format, e.g. "2020-10-30T15:26:48Z".
payment_initiation_metadatanullableobject
Metadata that captures what specific payment configurations an institution supports when making Payment Initiation requests.
supports_international_paymentsboolean
Indicates whether the institution supports payments from a different country.
maximum_payment_amountobject
A mapping of currency to maximum payment amount (denominated in the smallest unit of currency) supported by the insitution.
Example: {"GBP": "10000"}
supports_refund_detailsboolean
Indicates whether the institution supports returning refund details when initiating a payment.
standing_order_metadatanullableobject
Metadata specifically related to valid Payment Initiation standing order configurations for the institution.
supports_standing_order_end_dateboolean
Indicates whether the institution supports closed-ended standing orders by providing an end date.
supports_standing_order_negative_execution_daysboolean
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[string]
A list of the valid standing order intervals supported by the institution.
Possible values: WEEKLY, MONTHLY
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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "institutions": [
    {
      "country_codes": [
        "US"
      ],
      "institution_id": "ins_118923",
      "name": "Red Platypus Bank - Red Platypus Bank",
      "oauth": false,
      "products": [
        "assets",
        "auth",
        "balance",
        "transactions",
        "identity"
      ],
      "routing_numbers": []
    }
  ],
  "request_id": "Ggmk0enW4smO2Tp"
}