Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spitshake.io/llms.txt

Use this file to discover all available pages before exploring further.

​
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

ParameterTypeDefaultDescription
limitinteger10Number of items to return per page. Minimum 1, maximum 100.
afterinteger—Return items with an ID greater than this value. Use the next cursor from the previous response.
beforeinteger—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

FieldTypeDescription
countintegerNumber of items returned in the current page (equal to the length of data).
nextinteger or nullThe cursor to use as the after parameter to fetch the next page. null when there are no more results.
previnteger or nullThe 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;
}

​
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

ParameterTypeDefaultDescription
pageinteger1The page number to retrieve (1-indexed).
per_pageinteger10Number 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

FieldTypeDescription
pageintegerThe current page number.
per_pageintegerThe number of items per page.
totalintegerThe total number of items across all pages.
total_pagesintegerThe 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

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.
Set limit=100 when iterating through all records to minimize the number of API calls and stay within rate limits.
Always use the next and prev values returned by the API. Cursor values are opaque and their format may change without notice.
When pagination.next is null, there are no more records. Do not make additional requests.
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.