> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wepayout.co/llms.txt
> Use this file to discover all available pages before exploring further.

# List Institutions

> Return the list of banks available in Brazil

# List Institutions

Return the list of banks available in Brazil.

## Query Parameters

<ParamField query="created_after" type="string">
  created after
</ParamField>

<ParamField query="created_before" type="string">
  created before
</ParamField>

<ParamField query="id" type="string">
  ISPB bank
</ParamField>

<ParamField query="ispb_authorized" type="boolean">
  To clear whether this bank is authorized ISPB
</ParamField>

<ParamField query="name" type="string">
  name of bank
</ParamField>

<ParamField query="order_by" type="string">
  Define the ordering of the query. Allowed values: `bank_id`, `code`, `name`, `document_name`, `logo`, `created_at`, `updated_at`. Default: `id`
</ParamField>

<ParamField query="page" type="integer">
  The current page that will be displayed on returned list.
</ParamField>

<ParamField query="per_page" type="integer">
  The number of banks that will be displayed per page on paginated lists.
</ParamField>

<ParamField query="sort" type="string">
  Define the sort order: ascending or descending
</ParamField>

<ParamField query="updated_after" type="string">
  updated after
</ParamField>

<ParamField query="updated_before" type="string">
  updated before
</ParamField>

## Response

<ResponseField name="id" type="number">
  internal id
</ResponseField>

<ResponseField name="code" type="string">
  bank code
</ResponseField>

<ResponseField name="ispb" type="string">
  ISPB code
</ResponseField>

<ResponseField name="name" type="string">
  Date name
</ResponseField>

<ResponseField name="logo" type="string">
  logo
</ResponseField>

<ResponseField name="created_at" type="string">
  Create date
</ResponseField>

<ResponseField name="updated_at" type="string">
  Update date
</ResponseField>

<ResponseField name="deleted_at" type="string">
  Delete date
</ResponseField>

<ResponseField name="ispb_authorized" type="boolean">
  Informs whether the ISPB of that institution is authorized or not
</ResponseField>

<ResponseExample>
  ```json 200 OK theme={null}
  [
    {
      "id": 1270,
      "code": "237",
      "ispb": "00000000",
      "name": "BANCO DO BRASIL S.A. - INSTITUIÇÃO DE PAGAMEN",
      "logo": null,
      "created_at": "2024-06-25 00:00:00.00",
      "updated_at": "2024-06-25 00:00:00.00",
      "deleted_at": null,
      "ispb_authorized": false
    }
  ]
  ```
</ResponseExample>

## Use Cases

### Display Bank List in UI

```javascript theme={null}
async function loadBankOptions() {
  const response = await fetch('https://api.wepayments.com/v1/banks/institutions', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  });
  
  const { data } = await response.json();
  
  const select = document.getElementById('bank-select');
  data.forEach(bank => {
    const option = document.createElement('option');
    option.value = bank.code;
    option.textContent = bank.name;
    select.appendChild(option);
  });
}
```

### Validate Bank Code

```javascript theme={null}
async function validateBankCode(code) {
  const response = await fetch('https://api.wepayments.com/v1/banks/institutions', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  });
  
  const { data } = await response.json();
  return data.some(bank => bank.code === code);
}
```

### Search Banks

```javascript theme={null}
async function searchBanks(query) {
  const response = await fetch('https://api.wepayments.com/v1/banks/institutions', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  });
  
  const { data } = await response.json();
  const lowerQuery = query.toLowerCase();
  
  return data.filter(bank => 
    bank.name.toLowerCase().includes(lowerQuery) ||
    bank.short_name.toLowerCase().includes(lowerQuery)
  );
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Cache the Response">
    The list of institutions doesn't change frequently. Cache the response to reduce API calls:

    ```javascript theme={null}
    const CACHE_KEY = 'banks_list';
    const CACHE_DURATION = 7 * 24 * 60 * 60 * 1000; // 7 days

    async function getBanks() {
      const cached = localStorage.getItem(CACHE_KEY);
      const timestamp = localStorage.getItem(`${CACHE_KEY}_time`);
      
      if (cached && timestamp) {
        const age = Date.now() - parseInt(timestamp);
        if (age < CACHE_DURATION) {
          return JSON.parse(cached);
        }
      }
      
      const response = await fetch('https://api.wepayments.com/v1/banks/institutions', {
        headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
      });
      
      const data = await response.json();
      localStorage.setItem(CACHE_KEY, JSON.stringify(data));
      localStorage.setItem(`${CACHE_KEY}_time`, Date.now().toString());
      
      return data;
    }
    ```
  </Accordion>

  <Accordion title="Handle Errors Gracefully">
    Always handle potential errors when fetching the bank list:

    ```javascript theme={null}
    try {
      const banks = await fetchBanks();
      displayBanks(banks);
    } catch (error) {
      console.error('Failed to load banks:', error);
      showErrorMessage('Unable to load bank list. Please try again later.');
    }
    ```
  </Accordion>

  <Accordion title="Filter by Type">
    If you only need specific types of institutions, filter the results:

    ```javascript theme={null}
    const banks = await fetchBanks();
    const traditionalBanks = banks.data.filter(bank => bank.type === 'bank');
    ```
  </Accordion>
</AccordionGroup>

## Rate Limiting

This endpoint is subject to rate limiting. Please cache the response and avoid making excessive requests.