Sandbox Mode

Sandbox mode lets you develop and test without sending real emails or consuming your monthly document quota.

How to use sandbox mode

Set "sandbox": true in your request body:

curl -X POST https://zipzign.com/api/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "signable",
    "sandbox": true,
    "title": "Test Document",
    "content": "<p>Hello {{name}}</p>",
    "variables": { "name": "World" },
    "signers": [
      { "name": "Test User", "email": "test@example.com" }
    ]
  }'

Sandbox behavior

Behavior	Sandbox	Production
Emails sent	No	Yes
Counts against quota	No	Yes
Documents auto-deleted	After 24 hours	Never
PDF generation	Full quality	Full quality
Signing flow	Fully functional	Fully functional
Payment flow	Stripe test mode	Stripe live mode
Webhooks fired	Yes	Yes

Identifying sandbox documents

Sandbox documents include "sandbox": true in all API responses and webhook payloads:

{
  "id": "doc_abc123",
  "sandbox": true,
  "status": "awaiting_signatures",
  ...
}

Signing sandbox documents

Even though no emails are sent, the signing URL is still active. You can open docUrl directly in your browser to test the signer experience.

Payments in sandbox mode

Sandbox payment documents use Stripe test mode automatically. Use Stripe's test card numbers:

Success: 4242 4242 4242 4242
Decline: 4000 0000 0000 0002

Auto-deletion

A daily cleanup job deletes all sandbox documents older than 24 hours. Do not store sandbox document IDs as permanent references.

Tip

Use a dedicated ZIPZIGN_API_KEY_TEST environment variable for your sandbox key to avoid accidentally running tests against production.

Updated on: 16/04/2026

Was this article helpful?

Thank you!