> ## 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.

# Test Mode

> Safely develop and test your integration without affecting live documents or consuming plan quotas.

## 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        |

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

## 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

```bash theme={null}
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:**

```json theme={null}
{
  "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

```bash theme={null}
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:**

```json theme={null}
{
  "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

```bash theme={null}
curl -X GET https://your-instance.spitshake.io/api/settings/test_mode \
  -H "X-Auth-Token: YOUR_API_TOKEN"
```

**Response:**

```json theme={null}
{
  "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:

```bash theme={null}
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:**

```json theme={null}
{
  "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"
    }
  ]
}
```

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

### 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:

```json theme={null}
{
  "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"
    }
  }
}
```

<Tip>
  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.
</Tip>

## Switching Between Test and Live

### Before Going Live

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Verify error handling">
    Intentionally trigger errors (invalid template ID, missing required fields, expired submission) and confirm your integration handles them gracefully.
  </Step>

  <Step title="Disable test mode">
    Call `PUT /api/settings/test_mode` with `{"enabled": false}` to switch to live mode.
  </Step>

  <Step title="Monitor your first live submissions">
    Watch the dashboard and webhook logs for the first few live submissions to confirm everything works as expected.
  </Step>
</Steps>

### 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.

```bash theme={null}
# 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:**

```json theme={null}
{
  "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.

```bash theme={null}
curl -X DELETE https://your-instance.spitshake.io/api/submissions/test \
  -H "X-Auth-Token: YOUR_API_TOKEN"
```

**Response:**

```json theme={null}
{
  "deleted_count": 47,
  "message": "47 test submissions and their associated data have been permanently deleted."
}
```

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