Zintara API pagination: walk lead pages and reconcile changing data

Define the decision

The reviewed GET /api/leads handler accepts page and limit, plus q and status filters. It defaults invalid or out-of-range limits to 200 and permits limits up to 1,000. Pagination is not a snapshot transaction across requests.

Work through the procedure

1. Use a leads:read key and explicit page and limit values.
2. Keep filters identical across the walk.
3. Process records by stable lead ID and follow hasNextPage.
4. Record the start and end time, then reconcile if the source changed during the walk.

Worked example

The following is a synthetic example for this procedure, not a customer result or performance benchmark.

GET /api/leads?page=1&limit=100&status=new
Response fields: ok, leads, total, page, totalPages, hasNextPage
Next request: same filters with page=2
Consumer record: lead ID plus retrieval time

Read the result

Insertions or deletions can move records between offset-based pages. Deduplicating by lead ID prevents repeated processing but does not by itself prove that no record was skipped.

Check before moving on

1. Handle an empty leads array without inventing a missing record.
2. Do not assume campaign enrollment pages use the same response envelope.

Limits and next action

For a critical migration, use a controlled quiet window or reconciliation pass. There is no documented snapshot cursor in this endpoint.

Source: Zintara implementation and product context