Test Mode

Overview

Test mode lets you build and verify your DocuTrust integration without creating real submissions, sending actual emails to signers, or counting against your plan’s monthly quotas. When test mode is active, all API operations behave identically to production, but the data is isolated and clearly marked as test data.

What Test Mode Does

Behavior	Live Mode	Test Mode
Submissions count toward plan quota	Yes	No
Emails sent to submitters	Yes	No (simulated)
Webhooks delivered	Yes	Yes (with `"test": true` in payload)
Signed documents generated	Yes	Yes (watermarked with “TEST”)
Data visible in dashboard	Yes	Yes (filtered by mode toggle)
Audit log entries created	Yes	Yes (tagged as test)
API responses	Standard	Includes `"test": true` field

Test mode uses the same templates as live mode. Changes to templates affect both modes. Only submissions and their associated data are isolated.

Enabling Test Mode

Toggle test mode on or off with a single API call. The setting applies account-wide and takes effect immediately for all API tokens.

Enable Test Mode

curl -X PUT https://your-instance.spitshake.io/api/settings/test_mode \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'

Response:

{
  "test_mode": true,
  "enabled_at": "2026-04-09T10:00:00Z",
  "enabled_by": "admin@yourcompany.com",
  "message": "Test mode is now active. Submissions will not count toward your plan quota and emails will be simulated."
}

Disable Test Mode

curl -X PUT https://your-instance.spitshake.io/api/settings/test_mode \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Response:

{
  "test_mode": false,
  "disabled_at": "2026-04-09T12:00:00Z",
  "disabled_by": "admin@yourcompany.com",
  "message": "Test mode is now inactive. All submissions will be processed as live."
}

Check Current Mode

curl -X GET https://your-instance.spitshake.io/api/settings/test_mode \
  -H "X-Auth-Token: YOUR_API_TOKEN"

Response:

{
  "test_mode": true,
  "enabled_at": "2026-04-09T10:00:00Z",
  "enabled_by": "admin@yourcompany.com"
}

How Test Mode Affects Submissions

Creating Submissions

When test mode is active, submissions created via the API include a test flag:

curl -X POST https://your-instance.spitshake.io/api/submissions \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": 15,
    "submitters": [
      {
        "role": "First Party",
        "email": "jane.doe@example.com",
        "name": "Jane Doe",
        "external_id": "cust_12345",
        "metadata": {
          "department": "Legal"
        }
      }
    ]
  }'

Response:

{
  "id": 1042,
  "slug": "test_7k8m9n0p1q2r",
  "status": "pending",
  "test": true,
  "created_at": "2026-04-09T10:05:00Z",
  "completed_at": null,
  "template_id": 15,
  "submitters": [
    {
      "id": 2084,
      "uuid": "e5f6a7b8-c9d0-1234-5678-abcdef012345",
      "email": "jane.doe@example.com",
      "name": "Jane Doe",
      "role": "First Party",
      "status": "sent",
      "external_id": "cust_12345",
      "metadata": {
        "department": "Legal"
      },
      "signing_url": "https://your-instance.spitshake.io/s/test_a1b2c3d4e5f6"
    }
  ]
}

Test submission slugs are prefixed with test_ to make them easily identifiable. Signing URLs for test submissions also contain the test_ prefix.

Emails

No emails are sent to submitters during test mode. Instead, the API response includes the signing_url directly so you can open the form yourself. Email delivery events are simulated in webhook payloads for testing your webhook handler.

Signed Documents

Test mode generates real PDF documents so you can verify your document processing pipeline, but each page includes a diagonal “TEST DOCUMENT - NOT LEGALLY BINDING” watermark. Test documents are not suitable for legal or compliance purposes.

Webhooks in Test Mode

Webhooks are delivered normally during test mode, with an additional "test": true field in the payload:

{
  "event": "form.completed",
  "timestamp": "2026-04-09T14:32:00Z",
  "test": true,
  "data": {
    "submitter": {
      "id": 2084,
      "uuid": "e5f6a7b8-c9d0-1234-5678-abcdef012345",
      "email": "jane.doe@example.com",
      "name": "Jane Doe",
      "role": "First Party",
      "status": "completed",
      "external_id": "cust_12345",
      "metadata": {
        "department": "Legal"
      },
      "opened_at": "2026-04-09T14:20:00Z",
      "completed_at": "2026-04-09T14:32:00Z",
      "declined_at": null
    },
    "submission": {
      "id": 1042,
      "slug": "test_7k8m9n0p1q2r",
      "status": "completed",
      "template_id": 15
    },
    "template": {
      "id": 15,
      "name": "Employment Agreement"
    }
  }
}

Use the test field in your webhook handler to route test events to a separate processing path or skip side effects like updating your CRM.

Switching Between Test and Live

Before Going Live

Use this checklist to verify your integration is ready for production:

Verify webhook handling

Confirm your webhook endpoint correctly receives, verifies (HMAC signature), and processes all event types you subscribe to. Check that your handler is idempotent.

Test the complete signing flow

Create a test submission, open the signing URL, fill out all fields, and submit. Verify the resulting PDF, webhook deliveries, and any downstream processing.

Verify error handling

Intentionally trigger errors (invalid template ID, missing required fields, expired submission) and confirm your integration handles them gracefully.

Disable test mode

Call PUT /api/settings/test_mode with {"enabled": false} to switch to live mode.

Monitor your first live submissions

Watch the dashboard and webhook logs for the first few live submissions to confirm everything works as expected.

Data Isolation

Test and live data are fully isolated:

Dashboard filtering. The DocuTrust dashboard includes a mode toggle to view test or live submissions independently.
API filtering. List endpoints accept an optional test query parameter to filter results by mode. When omitted, only live submissions are returned.
No cross-contamination. Test submissions never appear in live reports, exports, or compliance audit logs.

# List only test submissions
curl -X GET "https://your-instance.spitshake.io/api/submissions?test=true&limit=25" \
  -H "X-Auth-Token: YOUR_API_TOKEN"

Response:

{
  "data": [
    {
      "id": 1042,
      "slug": "test_7k8m9n0p1q2r",
      "status": "completed",
      "test": true,
      "created_at": "2026-04-09T10:05:00Z",
      "completed_at": "2026-04-09T14:32:00Z",
      "template_id": 15,
      "submitters": [
        {
          "id": 2084,
          "uuid": "e5f6a7b8-c9d0-1234-5678-abcdef012345",
          "email": "jane.doe@example.com",
          "name": "Jane Doe",
          "role": "First Party",
          "status": "completed"
        }
      ]
    }
  ],
  "pagination": {
    "count": 1,
    "next": null,
    "prev": null
  }
}

Cleaning Up Test Data

Test submissions can be deleted in bulk from the dashboard or via the API. Deleting test data does not affect live submissions or plan quotas.

curl -X DELETE https://your-instance.spitshake.io/api/submissions/test \
  -H "X-Auth-Token: YOUR_API_TOKEN"

Response:

{
  "deleted_count": 47,
  "message": "47 test submissions and their associated data have been permanently deleted."
}

Deleting test data is permanent and cannot be undone. This removes all test submissions, signed documents, and audit log entries.

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

Overview

What Test Mode Does

Enabling Test Mode

Enable Test Mode

Disable Test Mode

Check Current Mode

How Test Mode Affects Submissions

Creating Submissions

Emails

Signed Documents

Webhooks in Test Mode

Switching Between Test and Live

Before Going Live

Data Isolation

Cleaning Up Test Data

​Overview

​What Test Mode Does

​Enabling Test Mode

​Enable Test Mode

​Disable Test Mode

​Check Current Mode

​How Test Mode Affects Submissions

​Creating Submissions

​Emails

​Signed Documents

​Webhooks in Test Mode

​Switching Between Test and Live

​Before Going Live

​Data Isolation

​Cleaning Up Test Data

Overview

What Test Mode Does

Enabling Test Mode

Enable Test Mode

Disable Test Mode

Check Current Mode

How Test Mode Affects Submissions

Creating Submissions

Emails

Signed Documents

Webhooks in Test Mode

Switching Between Test and Live

Before Going Live

Data Isolation

Cleaning Up Test Data