Pagination

The Lending Core uses three list shapes, chosen per resource family. Learn which one an endpoint returns before writing a traversal loop.

Operational lists: items with limit/offset

Most Lending Core lists — payments, fundings, statements, restrictions, reconciliation exceptions, external parties — accept limit (1–200, default 50) and offset and return an items array:

curl "$BASE/v1/loans/7204/payments?status=POSTED&limit=50" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender"

{
  "items": [
    {
      "paymentId": 9011,
      "loanRef": "7204",
      "status": "POSTED",
      "amount": "517.14",
      "currency": "USD"
    }
  ]
}

Customer and form-entry lists additionally echo the paging inputs — { "limit": 50, "offset": 0, "items": [...] }. A page shorter than limit is the end of the collection. Values outside the documented range return a validation error; they are not silently clamped.

History and search: items with nextCursor

Customer history, address history, and portfolio search page with an opaque cursor:

curl "$BASE/v1/customers/412/history?limit=50&cursor=cur_eyJzb3J0S2V5IjoiLi4uIn0" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender"

Send nextCursor unchanged on the next request and stop when it is null. Do not decode, edit, generate, compare, persist as a business identifier, or transfer a cursor between endpoints — it encodes a position under one endpoint’s ordering and may be signed or versioned. Repeat the same filters and caller context with the cursor; changing the query starts a new traversal, and the server can reject a cursor whose query fingerprint does not match.

Native lists: totalFilteredRecords with pageItems

The native loan and journal-entry lists take offset and limit (the loan list adds orderBy and sortOrder) and return a counted envelope:

{
  "totalFilteredRecords": 1,
  "pageItems": [
    { "id": 7204, "accountNo": "000007204", "clientId": 412, "status": { "code": "loanStatusType.active" } }
  ]
}

These are the only lists that report a total. Everywhere else, list responses omit totals by design: exact counts over filtered, permission-aware, changing datasets are expensive and stale before the next page. Use a named report when you need an auditable count.

Unknown parameters are rejected

A query parameter the endpoint does not document returns 400; it is never silently ignored. This catches misspelled or borrowed paging controls — Lending Core lists take limit and offset, not the servicing plane’s page-size parameter — before they quietly return the default page.

Ordering and concurrent changes

Each list documents its ordering — customer lists are newest-modified first, payment and funding lists newest first. Offset pages can skip or repeat rows when records are inserted mid-traversal, and resource states can change after a row was read. A live list is not a snapshot unless the endpoint explicitly says so.

Permission changes

Authorization applies to each page. If the client’s visibility changes mid-traversal, later pages reflect current access. Do not infer hidden-record counts from page sizes or cursors.

Servicing Plane contract

Lists under /v1/servicing keep that surface’s cursor convention: pageSize and cursor inputs with a data array, nextCursor, and hasMore in the response. The opaque-cursor rules above apply there to every list.