# List institutions

## ▶️ Usage

With the List Institutions method, you can:

1. List all institutions Belvo has available.

## 📖 Pagination

This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.

## 🔦 Filtering Responses

Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.

Endpoint: GET /api/institutions/
Version: 1.223.0
Security: basicAuth

## Query parameters:

  - `page_size` (integer)
    Indicates how many results to return per page. By default we return 100 results per page.

ℹ️ The minimum number of results returned per page is 1 and the maximum is 1000. If you enter a value greater than 1000, our API will default to the maximum value (1000).
    Example: 100

  - `page` (integer)
    A page number within the paginated result set.
    Example: 1

  - `display_name` (string)
    Return institutions that partially match this display name.
    Example: "Erebor Bank"

  - `country_code` (string)
    Return institutions only for this two-letter country code.
    Example: "MX"

  - `country_code__in` (array)
    Return institutions only for these two-letter country codes.
    Example: ["BR"]

  - `resources__allin` (array)
    Return institutions that support this combination resources.
    Example: ["OWNERS"]

  - `name` (string)
    Return an institution with this Belvo-designated name.
    Example: "planet_mx_retail"

  - `name__in` (array)
    Return institutions with one or more of these Belvo-designated names.
    Example: ["planet_mx_retail"]

  - `status` (string)
    Return institutions with the given status. You can choose between healthy or down.
    Example: "healthy"

  - `status__in` (array)
    Return institutions with one of the given statuses. You can choose between healthy or down.
    Example: ["healthy"]

  - `type` (string)
    Return institutions of this type. You can choose between bank, fiscal, or employment.
    Enum: "bank", "fiscal", "employment"

  - `type__in` (array)
    Return institutions of one of these types. You can choose between bank, fiscal, or employment.
    Enum: "bank", "fiscal", "employment"

  - `website` (string)
    Return institutions with this website URL.
    Example: "https://www.erebor.mx"

## Response 200 fields (application/json):

  - `count` (integer)
    The total number of results in your Belvo account.
    Example: 130

  - `next` (string,null)
    The URL to next page of results. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is null.

In our documentation example, we use {endpoint} as a placeholder value. In production, this value will be replaced by the actual endpoint you are currently using (for example, accounts or owners).
    Example: "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2"

  - `previous` (string,null)
    The URL to the previous page of results. If there is no previous page, the
value is null.

  - `results` (array)
    Array of institution objects.

  - `results.id` (integer)
    The ID of the institution as designated by Belvo.
    Example: 1003

  - `results.name` (string)
    The name of the institution, as designated by Belvo.
    Example: "erebor_mx_retail"

  - `results.type` (string)
    The type of institution. We return one of the following values:

  - bank
  - fiscal
  - employment
    Enum: "bank", "fiscal", "employment"

  - `results.website` (string,null)
    The URL of the institution's website.
    Example: "https://www.erebor.com/"

  - `results.display_name` (string)
    The customer-facing name of the institution.
    Example: "Erebor Mexico"

  - `results.country_codes` (array)
    The country codes where the institution is available, for example:
- 🇧🇷 BR (Brazil)
- 🇨🇴 CO (Colombia)
- 🇲🇽 MX (Mexico)
    Example: ["MX"]

  - `results.primary_color` (string)
    The primary color on the institution's website.
    Example: "#056dae"

  - `results.logo` (string,null)
    The URL of the institution's logo.
    Example: "https://belvo-api-media.s3.amazonaws.com/logos/erebor_logo.svg"

  - `results.icon_logo` (string,null)
    The URL of the institution's icon logo.
    Example: "https://statics.belvo.io/widget/images/institutions/erebor.svg"

  - `results.text_logo` (string,null)
    The URL of the institution's text logo.
    Example: "https://statics.belvo.io/widget/images/institutions/erebor.svg"

  - `results.form_fields` (array)

  - `results.form_fields.name` (string)
    The username, password, or username type field.
    Example: "username"

  - `results.form_fields.type` (string)
    The input type for the form field. For example, string.
    Example: "text"

  - `results.form_fields.label` (string)
    The label of the form field. For example:
- Client number
- Key Bancanet
- Document
    Example: "Client number"

  - `results.form_fields.validation` (string)
    The type of input validation used for the field.
    Example: "^.{1,}$"

  - `results.form_fields.placeholder` (string)
    The placeholder text in the form field.
    Example: "ABC333333A33"

  - `results.form_fields.validation_message` (string)
    The message displayed when an invalid input is provided in the form field.
    Example: "Invalid client number"

  - `results.form_fields.values` (array)
    If the form field is for documents, the institution may require additional
input regarding the document type.

  - `results.form_fields.values.code` (string)
    The code of the document.
    Example: "001"

  - `results.form_fields.values.label` (string)
    The label for the field. For example:
- Cédula de Ciudadanía
- Cédula de Extranjería
- Pasaporte
    Example: "Cédula de Ciudadanía"

  - `results.features` (array)
    The features that the institution supports. If the institution has no special features, then Belvo returns an empty array.

Here is a list of the available features:
- token_required indicates that the institution may require a token during link creation or when making any other requests.

  - `results.features.name` (string)
    The name of the feature.
    Example: "token_required"

  - `results.features.description` (string)
    The description of the feature.
    Example: "The institution may require a token during link creation or login"

  - `results.resources` (array)
    A list of Belvo resources that you can use with the institution. This list includes one or more of the following resources:

  - ACCOUNTS
  - BALANCES
  - BILLS
  - EMPLOYMENTS
  - EMPLOYMENT_RECORDS
  - FINANCIAL_STATEMENTS
  - INCOMES
  - INVESTMENTS
  - INVESTMENT_TRANSACTIONS
  - INVOICES
  - OWNERS
  - RECURRING_EXPENSES
  - RISK_INSIGHTS
  - TRANSACTIONS
  - TAX_COMPLIANCE_STATUS
  - TAX_RETENTIONS
  - TAX_RETURNS
  - TAX_STATUS
    Example: ["ACCOUNTS","BALANCES","INCOMES","OWNERS","RECURRING_EXPENSES","RISK_INSIGHTS","TRANSACTIONS"]

  - `results.integration_type` (string)
    The type of technology used to access the institution. We return one of the following values:

- credentials: Uses Belvo's scraping technology, combined with user credentials, to perform requests.
- openfinance: Uses the bank's open finance API to perform requests.
    Enum: "credentials", "openfinance"

  - `results.status` (string)
    Indicates whether Belvo's integration with the institution is currently active (healthy) or undergoing maintenance (down).
    Enum: "healthy", "down"

  - `results.openbanking_information` (object,null)
    Information about the institution on the Open Finance environment.

  - `results.openbanking_information.description` (string,null)
    A short description of the institution on the Open Finance environment. Extracted from Open Finance regulated institutions listing.
    Example: "A 1ss Bank é uma fintech fundada em janeiro de 2020, com a missão de ajudar empresas com grandes ecossistemas a se tornarem fintechs, integrando e automatizando seus processos financeiros através de APIs e plataforma white-label."

  - `results.openbanking_information.participants` (array,null)
    List of brands' servers available from the institution in Open Finance. Extracted from Open Finance regulated institutions listing.
    Example: ["1ss Bank"]

  - `results.openbanking_information.authorization_server_id` (string,null)
    The authorization server ID (UUID) of the institution on the Open Finance Environment.
    Example: "aa18fcd3-2f0b-40b1-87db-8930b10b78b1"

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code (access_to_resource_denied) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    A short description of the error. 


For access_to_resource_denied errors, the description is:
  
  - You don't have access to this resource..
    Example: "You don't have access to this resource."

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    A unique error code (not_found) that allows you to classify and handle the error programmatically.
    Example: "not_found"

  - `message` (string)
    A short description of the error.


For not_found errors, the description is:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    A unique error code (request_timeout) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors.
    Example: "request_timeout"

  - `message` (string)
    A short description of the error. 


For request_timeout errors, the description is:
  
  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code (unexpected_error) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors.
    Example: "unexpected_error"

  - `message` (string)
    A short description of the error. 


For unexpected_error errors, the description is:
  
  - Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution.
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"