Paginate Cleo Pay API List Endpoints

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

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

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:

Paginated response envelope

{
  "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:

Fetch page 2 with 10 items per page

curl --request GET \
  --url 'https://api.cleo-pay.com/v1/contacts?page=2&pageSize=10' \
  --header 'Authorization: Bearer <token>'

Paginated contacts response

{
  "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.

Search active payees matching 'acme'

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.

List approved payables

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:

Fetch all contacts (JavaScript)

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;
}

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

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

Get Started

Core Concepts

How-To Guides

Reference

Paginate Cleo Pay API List Endpoints

Query parameters

Response shape

Search and filter parameters

Contacts (`GET /v1/contacts`)

Payables (`GET /v1/payables`)

Iterate through all pages

​Endpoints that support pagination

​Query parameters

​Response shape

​Basic pagination example

​Search and filter parameters

​Contacts (GET /v1/contacts)

​Payables (GET /v1/payables)

​Iterate through all pages

Endpoints that support pagination

Query parameters

Response shape

Basic pagination example

Search and filter parameters

Contacts (`GET /v1/contacts`)

Payables (`GET /v1/payables`)

Iterate through all pages