Skip to Content

Pagination

Walk any list endpoint with limit, cursor, and nextCursor, get a total count, and sync changes incrementally

Every list that grows with your data returns one page of results at a time, in the same shape:

{
  "data": [],
  "hasMore": true,
  "nextCursor": "eyJjIjoiY3JlYXRlZEF0IiwidiI6IjIwMjYtMTAtMDFUMDg6MDA6MDAuMDAwWiIsImlkIjoiY200azJ4OXAxMDAwMWFiY2QxMjM0ZWZnaCJ9"
}
FieldDescription
dataThe items on this page.
hasMoretrue if more items follow this page; false on the last page.
nextCursorAn opaque string to pass as cursor to get the next page, or null on the last page.
totalThe number of items that match your filters. Present only when you send include=total. See Get the total.

A paginated list takes the following query parameters:

ParameterDescription
limitThe maximum number of items to return, from 1 to 100. Default: 25.
cursorThe nextCursor from the previous response. Leave it out to get the first page.
includetotal adds total to the response.

To get the next page, send the same request again with cursor set to the nextCursor you received, and keep every other query parameter unchanged. Stop when hasMore is false.

This page describes API version 2026-10. In 2026-09, lists return the array under a name of their own, such as documents, and most page with page and perPage. In 2026-10, page and perPage return 400 VALIDATION_FAILED. For the differences, see Upgrading to 2026-10.

Walk a list

The following samples list every document in the workspace, 100 at a time:

#!/usr/bin/env bash
# Requires jq.
cursor=""

while true; do
  args=(--data-urlencode "limit=100")
  [ -n "$cursor" ] && args+=(--data-urlencode "cursor=$cursor")

  page=$(curl -sS --fail-with-body -G https://app.sajn.se/api/v1/documents \
    -H "Authorization: Bearer $SAJN_API_KEY" \
    -H "Sajn-Version: 2026-10" \
    "${args[@]}") || { echo "$page" >&2; exit 1; }

  echo "$page" | jq -c '.data[] | {id, name, status}'

  [ "$(echo "$page" | jq -r '.hasMore')" = "true" ] || break
  cursor=$(echo "$page" | jq -r '.nextCursor')
done

Each sample reads your API key from the SAJN_API_KEY environment variable. Every paginated list has the same shape, so to walk another list, change the path, such as /contacts. Add filters to the first request only; the loops keep them on every page.

A full walk of a large list sends many requests in a short time. To stay within your per-minute limit, see Rate limits.

Walk a full list once, such as for a first import. Don't walk it again on a schedule to find changes. Learn about changes from webhooks, and sync changes incrementally with updatedAfter.

Paginated and bounded lists

Lists that grow with your data, such as documents, contacts, folders, and a document's comments, are paginated as this page describes.

Lists that their parent bounds aren't paginated. They return every item in one response, as { data, hasMore: false, nextCursor: null }, and don't take limit or cursor. The following lists are bounded:

  • A document's parties, fields, field values, signatures, files, links, reminders, and delegations.
  • A template's parties and fields.
  • The workspace's roles and permissions.
  • The /api/v1/helpers lists, such as countries and currencies.

Get the total

A list returns total only when you send include=total, because counting every match takes time. Ask for it on the first page only, when you need it, such as to show a count in your UI:

curl -G https://app.sajn.se/api/v1/contacts \
  -H "Authorization: Bearer $SAJN_API_KEY" \
  -H "Sajn-Version: 2026-10" \
  --data-urlencode "limit=20" \
  --data-urlencode "include=total"

The response is similar to the following:

{
  "data": [],
  "hasMore": true,
  "nextCursor": "eyJwIjoyfQ",
  "total": 87
}

To know whether another page follows, read hasMore, not total.

Sort a list

Most lists return the newest items first. The following lists also take orderBy and orderDirection, where orderDirection is asc or desc, with a default of desc:

ListorderByDefault
GET /api/v1/documentscreatedAt, updatedAt, name, completedAt, or expiresAtcreatedAt
GET /api/v1/formscreatedAt or updatedAtcreatedAt
GET /api/v1/forms/{id}/submissionsstartedAt or updatedAtstartedAt
GET /api/v1/membersjoinedAt, lastActiveAt, or namejoinedAt

Documents with no completedAt or expiresAt value sort last in both directions.

A cursor belongs to the sort order it was issued for. A cursor sent with a different orderBy returns 400 VALIDATION_FAILED. To change the order, start again without cursor.

Changes during a walk

The document, form, form submission, event, webhook, webhook delivery, tag, folder, approval request, document activity, and document message lists page by keyset: the cursor marks the last item you received. Items that are created or deleted while you walk never shift the items you haven't read yet, and every orderBy works the same way. This makes these lists the right choice for syncing data.

The other paginated lists, such as contacts and templates, page by position. If items are created or deleted while you walk one, items can shift between pages, so a walk can skip or repeat an item. Deduplicate by id.

Sync changes incrementally

To keep a copy of your documents up to date, sort by the time of the last change, oldest first, and start at the newest change you've stored:

curl -G https://app.sajn.se/api/v1/documents \
  -H "Authorization: Bearer $SAJN_API_KEY" \
  -H "Sajn-Version: 2026-10" \
  --data-urlencode "updatedAfter=2026-10-01T08:00:00Z" \
  --data-urlencode "orderBy=updatedAt" \
  --data-urlencode "orderDirection=asc" \
  --data-urlencode "limit=100"

Walk the cursor until hasMore is false, and then store the largest updatedAt you received for the next run. A document that changes during the walk moves to the end of the list, so the walk still reaches it. updatedAfter includes its boundary, so the next run returns the last document again; deduplicate by id.

Forms and form submissions work the same way with updatedAfter and orderBy=updatedAt. To reconcile webhook events you might have missed, see Replay and reconcile.

Invalid cursors

A cursor is opaque. Don't parse it, build it, or store it for later use; pass it back unchanged on the next request. A cursor that the API can't read returns 400 VALIDATION_FAILED. To start over, send the request without cursor.

Next steps

  • Query parameters: filter formats, such as dates and multi-value filters.
  • Rate limits: the per-minute limit that a full walk counts against.
  • Errors: the error shape and every error code.

Was this page helpful?

Last updated on