Source: https://docs.debitura.com/developer-concepts/pagination

# Pagination

Debitura APIs use offset-based pagination for list endpoints. All paginated responses include metadata to help you navigate through results.

<a id="defaults"></a>

## Defaults

Default PageSize varies by endpoint:

-   **Cases endpoints** (Customer, Collection Partner, Referral Partner): default PageSize 10
-   **Users list endpoints** (Customer, Collection Partner APIs): default PageSize 50, capped at 100
-   **Referral Partner Clients endpoint** (`GET /clients`): default PageSize 50
-   **Maximum PageSize varies by endpoint:** Referral Partner `/cases` and `/reporting/transactions`, Customer `/tasks`, and Collection Partner `/managed-clients` reject values outside 1–100 with `400`. Referral Partner `/clients` and Customer/Collection Partner Users lists cap PageSize at 100. Customer and Collection Partner case-list endpoints do not enforce that maximum; use 100 or less for performance and consistency.

<a id="paginated-endpoints"></a>

## Paginated Endpoints

| API | Endpoint |
| --- | --- |
| Customer | `GET /cases`, `GET /Payments` |
| Collection Partner | `GET /cases`, `GET /managed-cases` |
| Referral Partner | `GET /cases`, `GET /clients`, `GET /reporting/transactions` |

<a id="request-parameters"></a>

## Request Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `Page` | integer | Page number (1-indexed). Defaults to 1. |
| `PageSize` | integer | Results per page. Defaults to 10 for Cases endpoints; Users list endpoints default to 50 (capped at 100), and the Referral Partner Clients endpoint also defaults to 50. Pagination validation varies by endpoint: Referral Partner `/cases` and `/reporting/transactions`, Customer `/tasks`, and Collection Partner `/managed-clients` reject values outside 1–100; Referral Partner `/clients` clamps that range instead. |

```http
GET /cases?Page=2&PageSize=25
XApiKey: {api_key}
```

All APIs use PascalCase parameters consistently.

<a id="response-metadata"></a>

## Response Metadata

Every paginated response includes a `page` object:

```json
{
  "cases": [ ... ],
  "page": {
    "totalResults": 147,
    "pageSize": 25,
    "currentPage": 2,
    "responseCount": 25,
    "totalPages": 6
  }
}
```

| Field | Description |
| --- | --- |
| `totalResults` | Total items matching your query |
| `pageSize` | Items per page (as requested or default) |
| `currentPage` | Current page number |
| `responseCount` | Items returned in this response |
| `totalPages` | Total pages available |

<a id="iterating-through-pages"></a>

## Iterating Through Pages

Increment `Page` until `currentPage` equals `totalPages`:

```javascript
let page = 1;
let totalPages = 1;

do {
  const response = await fetch(`/cases?Page=${page}&PageSize=100`);
  const data = await response.json();

  // Process data.cases

  totalPages = data.page.totalPages;
  page++;
} while (page <= totalPages);
```

Alternatively, stop when `responseCount` is less than `pageSize`.

<a id="combining-with-filters"></a>

## Combining with Filters

Pagination works with [filtering and sorting](https://docs.debitura.com/developer-concepts/filtering-and-sorting.md). The `totalResults` reflects the filtered count, not the total dataset.

```http
GET /cases?Statuses=Active&Sort=date:desc&Page=1&PageSize=50
```