Pagination

Embarc’s REST endpoints share a consistent pagination contract. Below, we provide an example of how /clients behaves. The same contract applies to all other API's the support Pagination

Core Query Parameters

Parameter	Type	Default	What it controls
`limit`	number	200	Maximum rows returned. Supply a positive integer; `0` or negative numbers triggers the default pagination size for the API.
`offset`	number	0	Zero-based row offset. For “page N,” use `offset = N × limit`.
`orderBy`	string	Primary key	Column/field to sort by (e.g., `displayName`, `id`).
`sortOrder`	string	ASC	`ASC` or `DESC`.
`paged`	boolean	false	When `true`, wraps results in `{ "totalFilteredRecords": …, "pageItems": [...] }`.
`fields`	string	–	Optional projection (`fields=id,displayName,status`) to slim payloads.

Combine these with domain filters (status=active, officeId=3, etc.) to narrow the result set before paging.

Example

GET /clients?offset=100&limit=25&paged=true

{
  "totalFilteredRecords": 612,
  "pageItems": [
    {
      "id": 141,
      "accountNo": "000000141",
      "displayName": "Chase, Franklin",
      "status": { "id": 300, "code": "clientStatusType.active", "value":
"Active" }
    }
  ]
}

Use totalFilteredRecords to compute UI page counts (Math.ceil(totalFilteredRecords / limit)).

Example – With Filtering

GET /embrc-provider/api/v1/clients
    ?offset=75
    &limit=25
    &fields=id,accountNo,displayName,status
    &orderBy=displayName
    &sortOrder=ASC

Only the requested fields are returned—ideal for list views and dashboards.

Implementation Notes

Missing limit defaults to 200, protecting clients from unbounded responses.
paged=true swaps the bare array for a page envelope (totalFilteredRecords, pageItems) that’s easy to plug into pagination controls.
Provide fields that exist in the resultset (e.g., displayName, officeName, status_enum) for sorting. Invalid names yield validation errors.

Best Practices

Always send orderBy + sortOrder when paginating to keep ordering stable as new customers or loans arrive.
Layer resource filters (status=active, loanOfficerId=7) before paging to reduce the data you fetch.
Combine pagination with fields to minimize payload size for accounting/ reporting grids.
Remember offset is zero-based: page 0 → offset=0, page 1 → offset=limit, page 2 → offset=2×limit, and so on.