Pagination

How list endpoints page, sort and search.

Every endpoint that returns a list is paged. Ask for a page, render it, and use the response to decide whether to ask for another.

Query parameters

ParameterTypeDefaultNotes
pageinteger0Zero-based. The first page is 0.
sizeinteger20Records per page. Large values are capped.
searchstring—Free-text search. Which fields it covers depends on the endpoint.
sortBystringendpoint defaultSort key. An unsupported key falls back to the endpoint's default order.
sortDirectionstringascasc or desc.

Endpoint filters — subjectType, status, from, to, unreadOnly — combine with these.

An invalid page, size or sortBy is normalised to a safe default rather than rejected.

The response

Every paged response uses the same envelope:

{
  "items": [],
  "page": 0,
  "size": 20,
  "totalItems": 42,
  "totalPages": 3,
  "hasNext": true,
  "hasPrevious": false
}
FieldMeaning
itemsThe records for this page.
pageThe zero-based page returned.
sizeThe page size the server used — not necessarily the one you asked for.
totalItemsTotal matching records.
totalPagesTotal pages for the current filters.
hasNexttrue when another page is available.
hasPrevioustrue when a previous page is available.

Walking every page

Branch on hasNext rather than comparing page against totalPages:

page = 0
do
  response = GET /api/v1/checks/definitions?page={page}&size=50
  process(response.items)
  page = response.page + 1
while response.hasNext

Keep the filters identical across the loop. Changing search or a date range mid-walk repages the results and you will miss records or see them twice.

Fewer, larger pages cost fewer requests and are less likely to hit the rate limit — but size is capped, so read back the size the server actually used rather than assuming you got what you asked for.

Example

curl "https://api.verifisha.com/api/v1/checks/definitions?subjectType=INDIVIDUAL&page=0&size=10" \
  -H "Authorization: Bearer vrf_live_..."

Searching and sorting:

curl "https://api.verifisha.com/api/v1/checks/definitions?search=credit&page=0&size=20&sortBy=name&sortDirection=asc" \
  -H "Authorization: Bearer vrf_live_..."

Sandbox and live responses share this envelope. Only the data differs.

Paged endpoints

On this page