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
| Parameter | Type | Default | Notes |
|---|---|---|---|
page | integer | 0 | Zero-based. The first page is 0. |
size | integer | 20 | Records per page. Large values are capped. |
search | string | — | Free-text search. Which fields it covers depends on the endpoint. |
sortBy | string | endpoint default | Sort key. An unsupported key falls back to the endpoint's default order. |
sortDirection | string | asc | asc 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
}| Field | Meaning |
|---|---|
items | The records for this page. |
page | The zero-based page returned. |
size | The page size the server used — not necessarily the one you asked for. |
totalItems | Total matching records. |
totalPages | Total pages for the current filters. |
hasNext | true when another page is available. |
hasPrevious | true 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.hasNextKeep 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.