Pagination

Overview

DocuTrust API endpoints that return lists of resources support pagination to keep response sizes manageable. The primary pagination method is cursor-based, which provides stable, performant iteration even as new records are created or deleted. Some endpoints additionally support page-based pagination for simpler random-access use cases.

Cursor-Based Pagination

Cursor-based pagination uses resource IDs as cursors. You pass an after or before parameter to fetch the next or previous page of results.

Parameters

Parameter	Type	Default	Description
`limit`	integer	`10`	Number of items to return per page. Minimum `1`, maximum `100`.
`after`	integer	—	Return items with an ID greater than this value. Use the `next` cursor from the previous response.
`before`	integer	—	Return items with an ID less than this value. Use the `prev` cursor from the previous response.

You may pass after or before, but not both in the same request. If neither is provided, the first page of results is returned.

Response Format

Every paginated response includes a data array and a pagination object:

{
  "data": [
    {
      "id": 447,
      "slug": "7k8m9n0p1q2r",
      "status": "completed",
      "created_at": "2026-04-08T09:12:00Z",
      "completed_at": "2026-04-08T11:45:00Z",
      "template_id": 15,
      "submitters": [
        {
          "id": 890,
          "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "email": "jane.doe@example.com",
          "name": "Jane Doe",
          "role": "First Party",
          "status": "completed"
        }
      ]
    },
    {
      "id": 448,
      "slug": "8l9m0n1o2p3q",
      "status": "completed",
      "created_at": "2026-04-08T10:30:00Z",
      "completed_at": "2026-04-08T12:15:00Z",
      "template_id": 22,
      "submitters": [
        {
          "id": 891,
          "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "email": "bob.jones@acme.com",
          "name": "Bob Jones",
          "role": "Signer",
          "status": "completed"
        }
      ]
    },
    {
      "id": 449,
      "slug": "9m0n1o2p3q4r",
      "status": "pending",
      "created_at": "2026-04-08T11:00:00Z",
      "completed_at": null,
      "template_id": 15,
      "submitters": [
        {
          "id": 892,
          "uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
          "email": "alice.wong@globex.com",
          "name": "Alice Wong",
          "role": "First Party",
          "status": "sent"
        }
      ]
    }
  ],
  "pagination": {
    "count": 3,
    "next": 449,
    "prev": 447
  }
}

Pagination Object Fields

Field	Type	Description
`count`	integer	Number of items returned in the current page (equal to the length of `data`).
`next`	integer or null	The cursor to use as the `after` parameter to fetch the next page. `null` when there are no more results.
`prev`	integer or null	The cursor to use as the `before` parameter to fetch the previous page. `null` when on the first page.

Example: Fetching the First Page

curl -X GET "https://your-instance.spitshake.io/api/submissions?limit=10" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

Example: Fetching the Next Page

Use the next value from the previous response as the after parameter:

curl -X GET "https://your-instance.spitshake.io/api/submissions?limit=10&after=449" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

Example: Fetching the Previous Page

Use the prev value from the current response as the before parameter:

curl -X GET "https://your-instance.spitshake.io/api/submissions?limit=10&before=447" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

Iterating Through All Results

To retrieve every record, loop until pagination.next is null.

async function fetchAllSubmissions(apiToken) {
  const baseUrl = 'https://your-instance.spitshake.io/api/submissions';
  const allSubmissions = [];
  let afterCursor = null;

  while (true) {
    const params = new URLSearchParams({ limit: '100' });
    if (afterCursor) {
      params.set('after', afterCursor.toString());
    }

    const response = await fetch(`${baseUrl}?${params}`, {
      headers: { 'X-Auth-Token': apiToken },
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const result = await response.json();
    allSubmissions.push(...result.data);

    if (result.pagination.next === null) {
      break;
    }

    afterCursor = result.pagination.next;
  }

  return allSubmissions;
}

import requests

def fetch_all_submissions(api_token: str) -> list:
    base_url = "https://your-instance.spitshake.io/api/submissions"
    headers = {"X-Auth-Token": api_token}
    all_submissions = []
    after_cursor = None

    while True:
        params = {"limit": 100}
        if after_cursor is not None:
            params["after"] = after_cursor

        response = requests.get(base_url, headers=headers, params=params)
        response.raise_for_status()

        result = response.json()
        all_submissions.extend(result["data"])

        if result["pagination"]["next"] is None:
            break

        after_cursor = result["pagination"]["next"]

    return all_submissions

require 'net/http'
require 'json'
require 'uri'

def fetch_all_submissions(api_token)
  base_url = 'https://your-instance.spitshake.io/api/submissions'
  all_submissions = []
  after_cursor = nil

  loop do
    params = { 'limit' => 100 }
    params['after'] = after_cursor if after_cursor

    uri = URI(base_url)
    uri.query = URI.encode_www_form(params)

    request = Net::HTTP::Get.new(uri)
    request['X-Auth-Token'] = api_token

    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(request)
    end

    raise "API error: #{response.code}" unless response.is_a?(Net::HTTPSuccess)

    result = JSON.parse(response.body)
    all_submissions.concat(result['data'])

    break if result['pagination']['next'].nil?

    after_cursor = result['pagination']['next']
  end

  all_submissions
end

Page-Based Pagination

Some endpoints support traditional page-based pagination as an alternative. This is useful when you need to jump to a specific page or display a page count in a UI.

Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	The page number to retrieve (1-indexed).
`per_page`	integer	`10`	Number of items per page. Minimum `1`, maximum `100`.

Response Format

Page-based responses include total and total_pages in the pagination object:

{
  "data": [
    {
      "id": 15,
      "name": "Employment Agreement",
      "slug": "employment-agreement-v2",
      "external_id": "tmpl_emp_2026",
      "folder_name": "HR Documents",
      "source": "web",
      "created_at": "2026-03-01T08:00:00Z",
      "updated_at": "2026-04-09T09:15:00Z"
    },
    {
      "id": 22,
      "name": "Non-Disclosure Agreement",
      "slug": "nda-standard",
      "external_id": "tmpl_nda_2026",
      "folder_name": "Legal",
      "source": "web",
      "created_at": "2026-03-10T14:00:00Z",
      "updated_at": "2026-04-07T16:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 47,
    "total_pages": 5
  }
}

Page-Based Pagination Object Fields

Field	Type	Description
`page`	integer	The current page number.
`per_page`	integer	The number of items per page.
`total`	integer	The total number of items across all pages.
`total_pages`	integer	The total number of pages available.

Example Request

curl -X GET "https://your-instance.spitshake.io/api/templates?page=2&per_page=25" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

Page-based pagination can return inconsistent results if items are created or deleted between requests. Use cursor-based pagination when iterating through large or frequently-changing collections.

Best Practices

Prefer cursor-based pagination

Cursor-based pagination is more performant and stable than page-based pagination. Results remain consistent even when records are created or deleted between page fetches. Use it as your default approach.

Use the maximum limit for bulk exports

Set limit=100 when iterating through all records to minimize the number of API calls and stay within rate limits.

Do not construct cursors manually

Always use the next and prev values returned by the API. Cursor values are opaque and their format may change without notice.

Handle empty pages gracefully

When pagination.next is null, there are no more records. Do not make additional requests.

Respect rate limits between pages

When iterating through very large collections, monitor the X-RateLimit-Remaining header and add brief delays if needed. See the Errors guide for rate limit details.

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

Overview

Parameters

Response Format

Example: Fetching the First Page

Example: Fetching the Next Page

Example: Fetching the Previous Page

Iterating Through All Results

Parameters

Response Format

Example Request

Best Practices

​Overview

​Cursor-Based Pagination

​Parameters

​Response Format

​Pagination Object Fields

​Example: Fetching the First Page

​Example: Fetching the Next Page

​Example: Fetching the Previous Page

​Iterating Through All Results

​Page-Based Pagination

​Parameters

​Response Format

​Page-Based Pagination Object Fields

​Example Request

​Best Practices

Overview

Cursor-Based Pagination

Parameters

Response Format

Pagination Object Fields

Example: Fetching the First Page

Example: Fetching the Next Page

Example: Fetching the Previous Page

Iterating Through All Results

Page-Based Pagination

Parameters

Response Format

Page-Based Pagination Object Fields

Example Request

Best Practices