Pagination & Filtering

All ECOSIRE list endpoints support pagination, filtering, and sorting through query parameters.

---

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number (1-based)
limit	number	20	Items per page (max 100)
sortBy	string	varies	Field name to sort by (e.g., createdAt, name)
sortOrder	asc | desc	desc	Sort direction
search	string	—	Free-text search across name/email fields

Module-specific filters are documented on each module reference page. For example:

GET /api/contacts?page=2&limit=10&sortBy=name&sortOrder=asc&search=Acme
GET /api/orders?page=1&limit=25&status=confirmed&sortBy=createdAt&sortOrder=desc

---

Response Envelope

Every list response wraps results in a data + meta envelope:

{
  "data": [
    { "id": "...", "name": "Acme Corp", "..." : "..." },
    { "id": "...", "name": "Globex Ltd", "..." : "..." }
  ],
  "meta": {
    "total": 342,
    "page": 2,
    "limit": 10,
    "totalPages": 35
  }
}

Field	Description
meta.total	Total number of matching records (for the applied filters)
meta.page	Current page
meta.limit	Page size used
meta.totalPages	Math.ceil(total / limit)

---

Code Examples

TypeScript

interface PaginationMeta {
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

interface PaginatedResponse<T> {
  data: T[];
  meta: PaginationMeta;
}

async function fetchAll<T>(endpoint: string): Promise<T[]> {
  const results: T[] = [];
  let page = 1;
  const limit = 100;

  while (true) {
    const res = await fetch(
      `https://api.ecosire.com/api${endpoint}?page=${page}&limit=${limit}`,
      { headers: { Authorization: `Bearer ${process.env.ECOSIRE_API_KEY}` } }
    );
    const body: PaginatedResponse<T> = await res.json();
    results.push(...body.data);

    if (page >= body.meta.totalPages) break;
    page++;
  }

  return results;
}

// Usage
const allContacts = await fetchAll<Contact>('/contacts');

Python

import os, requests

def fetch_all(endpoint: str) -> list:
    base = "https://api.ecosire.com/api"
    headers = {"Authorization": f"Bearer {os.environ['ECOSIRE_API_KEY']}"}
    results, page, limit = [], 1, 100

    while True:
        r = requests.get(
            f"{base}{endpoint}",
            headers=headers,
            params={"page": page, "limit": limit}
        )
        r.raise_for_status()
        body = r.json()
        results.extend(body["data"])

        if page >= body["meta"]["totalPages"]:
            break
        page += 1

    return results

contacts = fetch_all("/contacts")

cURL (single page)

curl "https://api.ecosire.com/api/orders?page=1&limit=25&status=confirmed&sortBy=createdAt&sortOrder=desc" \
  -H "Authorization: Bearer eco_live_YOUR_KEY"

---

Sorting

Use sortBy with the exact field name returned in the response object. Common sortable fields:

Module	Sortable fields
Contacts	name, email, createdAt, updatedAt
Products	name, price, sku, createdAt
Orders	total, status, createdAt, updatedAt
Invoices	amount, dueDate, status, createdAt
Employees	name, department, hireDate

Attempting to sort by a non-sortable field returns 400 Bad Request.

---

Filtering

Most list endpoints accept module-specific filter parameters. Common patterns:

# Filter by status
GET /api/orders?status=confirmed

# Filter by date range
GET /api/invoices?from=2026-01-01&to=2026-03-31

# Filter by relation
GET /api/orders?contactId=018e1234-abcd-7000-8000-000000000001

# Combined
GET /api/products?category=software&inStock=true&sortBy=price&sortOrder=asc

All filter parameters are documented in each module's reference page.

---

Performance Tips

• Use limit=100 (the max) when fetching all records to minimize round trips.
• Use search for user-initiated lookups rather than fetching all and filtering client-side.
• Cache paginated responses for read-heavy UIs — many list endpoints are stable across seconds.
• For real-time data needs, consider Webhooks instead of polling list endpoints.