Pagination

List endpoints that support paging return a standard pagination object in the response so you can iterate through pages and build UIs (for example, “Page X of Y”).

Response shape

Every paginated list response includes a pagination object:

{
  "pagination": {
    "totalRecords": 100,
    "currentPage": 1,
    "totalPages": 10,
    "nextPage": 2,
    "prevPage": null
  }
}

Field	Type	Description
totalRecords	number	Total number of items matching the filters.
currentPage	number	The page number that was requested (1-indexed).
totalPages	number	Total number of pages (ceil of totalRecords divided by limit; at least 1).
nextPage	number or null	Page number for the next page, or null when there is no next page.
prevPage	number or null	Page number for the previous page, or null when on the first page.

The response also contains the list of items for the current page (for example, envelopes, templates, workspaces, contacts, or logs).

Endpoints that use pagination

• Envelopes: POST /public/envelope/list - request body can include page (default 1). Page size is 50.
• Templates: POST /public/template/list - request body can include page (default 1). Page size is 50.
• Workspaces: POST /public/workspace/list - request body can include page (default 1) and limit (default 50, max 50).
• Contacts: POST /public/contact/list - request body can include page (default 1) and limit (default 50, max 50).
• Logs: POST /public/logs/list - request body can include page (default 1) and limit (default 50, max 50).

How to iterate

1. Start with page set to 1 (or omit page to use the default).
2. Read the response: use pagination.nextPage for the next request.
3. If pagination.nextPage is null, there are no more pages.
4. Optionally use pagination.prevPage to go back, or pagination.totalPages and pagination.totalRecords for “Page X of Y” and progress UIs.

Example (pseudo-code):

let page = 1;
let allEnvelopes = [];

while (true) {
  const res = await client.post("/public/envelope/list", { body: { page } });
  allEnvelopes = allEnvelopes.concat(res.envelopes);
  if (res.pagination.nextPage === null) break;
  page = res.pagination.nextPage;
}

Example response

Listing envelopes (first page, 4 total records, 50 per page):

{
  "envelopes": [
    { "uuid": "...", "title": "Contract", "status": "draft" }
  ],
  "pagination": {
    "totalRecords": 4,
    "currentPage": 1,
    "totalPages": 1,
    "nextPage": null,
    "prevPage": null
  }
}

When there are more pages, nextPage is set (for example, 2), and you can request the next page by sending page: 2 in the next call.