Skip to main content

​
Overview

List endpoints in the HopNow API use page-based pagination to handle large result sets efficiently.

​
Parameters

All list endpoints support these query parameters:
ParameterTypeDefaultDescription
pageinteger1Page number (starts from 1)
sizeinteger10Number of items per page (1-100)

​
Example Request

GET /v1/customers/{customer_id}/accounts?page=2&size=20

​
Response Format

Paginated responses include metadata about the result set: 
{
  "items": [
    {
      "id": "acct_1234567890abcdef",
      "name": "Account 1",
      "status": "active",
      "created": "2024-01-01T00:00:00Z"
    },
    {
      "id": "acct_fedcba0987654321",
      "name": "Account 2",
      "status": "active",
      "created": "2024-01-02T00:00:00Z"
    }
  ],
  "total": 150,
  "page": 2,
  "size": 20,
  "pages": 8
}

​
Response Fields

FieldTypeDescription
itemsarrayArray of objects for the current page
totalintegerTotal number of items
pageintegerCurrent page number
sizeintegerNumber of items per page
pagesintegerTotal number of pages

​
Pagination Examples

​
First Page

GET /v1/customers/{customer_id}/accounts?page=1&size=25

​
Next Page

GET /v1/customers/{customer_id}/accounts?page=2&size=25

​
Last Page

# If pages = 8
GET /v1/customers/{customer_id}/accounts?page=8&size=25

​
Code Examples

def get_all_accounts(client, customer_id):
    accounts = []
    page = 1

    while True:
        response = client.get(
            f"/v1/customers/{customer_id}/accounts",
            params={"page": page, "size": 100}
        )
        data = response.json()

        accounts.extend(data["items"])

        if page >= data["pages"]:
            break

        page += 1

    return accounts

​
Best Practices

​
Choose Appropriate Page Sizes

  • Interactive UI: 10-25 items per page
  • Bulk processing: 50-100 items per page
  • Maximum allowed: 100 items per page

​
Handle Empty Results

response = client.get("/v1/customers/{customer_id}/accounts")
data = response.json()

if not data["items"]:
    print("No accounts found")
else:
    print(f"Found {len(data['items'])} accounts on this page")

​
Monitor Total Count

The total count helps track collection changes: 
first_response = client.get("/v1/accounts", params={"page": 1})
initial_total = first_response.json()["total"]

# After processing...
last_response = client.get("/v1/accounts", params={"page": 1})
final_total = last_response.json()["total"]

if final_total != initial_total:
    print(f"Collection size changed: {initial_total} → {final_total}")