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

# Paginate Cleo Pay API List Endpoints

> Cleo Pay list endpoints use page and pageSize query parameters. Learn how to paginate results and use search filters efficiently.

List endpoints in the Cleo Pay API return paginated results so you can retrieve large datasets efficiently without overwhelming your application or the API. All paginated endpoints use a consistent set of query parameters and return a uniform response shape.

***

## Endpoints that support pagination

| Endpoint           | Description                         |
| ------------------ | ----------------------------------- |
| `GET /v1/payables` | List payables (invoices).           |
| `GET /v1/contacts` | List contacts (vendors and payees). |

<Note>
  `GET /v1/bank-accounts` does **not** use pagination — it returns all of your bank accounts in a single response, regardless of count.
</Note>

***

## Query parameters

| Parameter  | Type   | Default | Constraints        | Description                  |
| ---------- | ------ | ------- | ------------------ | ---------------------------- |
| `page`     | number | `1`     | min `1`            | The page number to retrieve. |
| `pageSize` | number | `25`    | min `1`, max `100` | Number of items per page.    |

***

## Response shape

All paginated endpoints return a consistent envelope:

```json title="Paginated response envelope" theme={null}
{
  "items": [ /* ... array of resource objects ... */ ],
  "totalCount": 142
}
```

* **`items`** — the array of resource objects for the current page.
* **`totalCount`** — the total number of records matching your query (across all pages). Use this to compute the total number of pages: `Math.ceil(totalCount / pageSize)`.

***

## Basic pagination example

Retrieve the second page of contacts, with 10 contacts per page:

```bash title="Fetch page 2 with 10 items per page" theme={null}
curl --request GET \
  --url 'https://api.cleo-pay.com/v1/contacts?page=2&pageSize=10' \
  --header 'Authorization: Bearer <token>'
```

```json title="Paginated contacts response" theme={null}
{
  "items": [
    {
      "id": "contact_01hwxyz111",
      "displayName": "Acme Supplies LLC",
      "type": "payee",
      "status": "active",
      "paymentReady": true,
      "createdAt": "2024-05-15T08:00:00Z"
    },
    {
      "id": "contact_01hwxyz222",
      "displayName": "Beta Logistics Inc",
      "type": "payee",
      "status": "active",
      "paymentReady": false,
      "createdAt": "2024-05-20T09:30:00Z"
    }
  ],
  "totalCount": 142
}
```

***

## Search and filter parameters

Combine pagination with search and filter parameters to narrow results.

### Contacts (`GET /v1/contacts`)

| Parameter | Values               | Description                                                                                                                                       |
| --------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search`  | string               | Free-text search across contact name and email fields.                                                                                            |
| `status`  | `active`, `archived` | Filter by contact status. Defaults to returning both `active` and `archived` contacts; revoked contacts are excluded unless explicitly requested. |
| `type`    | `payee`, `business`  | Filter by contact type.                                                                                                                           |

```bash title="Search active payees matching 'acme'" theme={null}
curl --request GET \
  --url 'https://api.cleo-pay.com/v1/contacts?type=payee&status=active&search=acme&page=1&pageSize=25' \
  --header 'Authorization: Bearer <token>'
```

### Payables (`GET /v1/payables`)

| Parameter | Values           | Description                             |
| --------- | ---------------- | --------------------------------------- |
| `search`  | string           | Free-text search across payable fields. |
| `status`  | `approved`, etc. | Filter by payable status.               |

```bash title="List approved payables" theme={null}
curl --request GET \
  --url 'https://api.cleo-pay.com/v1/payables?status=approved&page=1&pageSize=50' \
  --header 'Authorization: Bearer <token>'
```

***

## Iterate through all pages

When you need to retrieve every record matching a query, loop through pages until you've collected `totalCount` items. Here's a JavaScript example:

```javascript title="Fetch all contacts (JavaScript)" theme={null}
async function getAllContacts(token) {
  const pageSize = 100;
  let page = 1;
  let allContacts = [];

  while (true) {
    const response = await fetch(
      `https://api.cleo-pay.com/v1/contacts?page=${page}&pageSize=${pageSize}`,
      {
        headers: { Authorization: `Bearer ${token}` },
      }
    );
    const data = await response.json();

    allContacts = allContacts.concat(data.items);

    // Stop when we've collected all records
    if (allContacts.length >= data.totalCount) {
      break;
    }

    page++;
  }

  return allContacts;
}
```

<Tip>
  Use the maximum `pageSize` of `100` when iterating all pages to minimize the number of API calls and stay well within rate limits.
</Tip>

The same pattern works for any paginated endpoint — just swap the URL and adjust your filters as needed.