Pagination and filters

Every list endpoint (GET /api/v1/charges, /people, /agreements...) uses page-number pagination.

Parameters

Sent via query string:

Parameter	Type	Default	Description
page	integer ≥ 1	1	Requested page (starts at 1).
per_page	integer 1–100	20	Items per page. Maximum 100.
sort_by	string	varies per resource	Sort field.
sort_order	asc | desc	varies per resource	Sort direction.

Legacy names (limit, sortField, sortDirection) remain accepted for compatibility; when both appear in the same request, the legacy one wins.

Response envelope

{
  "data": [
    { "id": "cmd8k2p4x0001ab3f", "status": "overdue", "amount": "1500.00", ... }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}

Field	Description
data	Items on the current page.
meta.total	Total items matching the filters (not just the ones returned).
meta.page	Current page.
meta.limit	Items per page effectively applied.
meta.totalPages	Total pages (ceil(total / limit)).

The last page may hold fewer items than per_page; a page beyond the end returns an empty data (not an error).

Filters

Resource-specific filters use snake_case in the query string (due_date_from, person_id, document_number, status...) — the full list lives on each endpoint in the reference. Filters coexist with pagination and sorting in the same request.

Examples

First page, defaults:

curl -H "Authorization: Bearer $DUNNING_TOKEN" \
  'https://api.dunning.kobana.com.br/api/v1/charges'

Page 3 with 50 items, overdue first:

curl -H "Authorization: Bearer $DUNNING_TOKEN" \
  'https://api.dunning.kobana.com.br/api/v1/charges?page=3&per_page=50&sort_by=due_date&sort_order=asc'

Filter + pagination:

curl -H "Authorization: Bearer $DUNNING_TOKEN" \
  'https://api.dunning.kobana.com.br/api/v1/charges?status=overdue&due_date_from=2026-07-01&per_page=100'

Iterating over all pages

async function fetchAll(url, token) {
  const out = [];
  let page = 1;
  while (true) {
    const res = await fetch(`${url}?page=${page}&per_page=100`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const { data, meta } = await res.json();
    out.push(...data);
    if (page >= meta.totalPages) break;
    page += 1;
  }
  return out;
}

Best practices

• per_page=100 minimizes the number of requests and spares your rate limit.
• For continuous sync, prefer incremental filters (dates) or webhooks over repeatedly sweeping everything.
• Don't assume a stable order without an explicit sort_by.
• Treat meta.total as a snapshot — items can enter/leave between pages while you iterate.