Pagination and sorting

Paging

List operations return one page at a time. Choose the page with these query parameters:

Parameter	Description
pageIndex	The 1-based page number. Defaults to 1.
pageSize	The maximum number of items per page. The default and maximum depend on the API.

Paged responses come back in an envelope:

{
  "pageIndex": 2,
  "pageSize": 50,
  "totalCount": 137,
  "items": [
    { "agentCode": "A1051", "firstName": "Dana", "lastName": "Lopez" }
  ]
}

totalCount is the total number of matching items across all pages. The number of pages is ceil(totalCount / pageSize).

Walking every page

var pageIndex = 1;
PagedResult<Agent> page;
do {
    page = await client.GetFromJsonAsync<PagedResult<Agent>>(
        $"acme/agents?pageIndex={pageIndex}&pageSize=50&sort=agentCode");
    Process(page.Items);
    pageIndex++;
} while ((pageIndex - 1) * page.PageSize < page.TotalCount);

tip

When you walk through a large collection, add a stable sort (such as agentCode) so items don't move between pages. For incremental syncs, filter with modifiedSince instead of re-reading everything.

Page size limits

API	Default	Maximum
Agency Management	Set per tenant	Set per tenant; typically 50, never more than 100
Agent Onboarding	50	Set per API
Business Insights (paged queries)	50	Set per query
Identity Management	Set per API	Set per API
Webhooks (subscriptions and deliveries)	Set per API	Set per API

If pageSize is over the maximum, the request fails with 400 and a message such as Page Size cannot exceed 50. It isn't silently truncated.

note

Webhooks paging parameters

The Webhooks API list operations currently use page and pageSize. page is 1-based, just like pageIndex.

Sorting

Operations that support sorting take a sort query parameter.

Agency Management

sort is a comma-separated list of <field> [asc|desc] clauses. The direction defaults to asc:

GET /acme/agents?sort=lastName,firstName
GET /acme/agents?sort=lastModified desc

Remember to URL-encode the space (sort=lastModified%20desc).

Sortable agent fields: agentCode, firstName, lastName, commonName, startDate, lastModified.

Identity Management

sort uses the field:direction form:

GET /acme/users?sort=createdAt:desc

Sortable user fields: username, email, agentCode, createdAt.

An unknown sort field causes a 400 validation error.