Sandbox & Testing

Overview

The sandbox environment is a full copy of the ZiaSign API that uses test data. Use it to develop and test your integration before going live.

Sandbox vs. Production

Feature	Sandbox	Production
Base URL	`https://sandbox.ziasign.com/api/v1`	`https://api.ziasign.com/api/v1`
API Keys	Separate sandbox keys	Production keys
Documents	Test documents	Production documents
Emails	Not delivered to real recipients	Delivered to real recipients
Webhooks	Delivered with `sandbox: true` flag	Delivered without flag
Rate Limits	Same as your plan	Same as your plan
Data Handling	Review current sandbox documentation	Review current product documentation

Getting Started

Go to Dashboard → Developer APIs → Credentials tab
Toggle the Sandbox switch
Create a sandbox API key
Use https://sandbox.ziasign.com/api/v1 as your base URL

Test Signers

In the sandbox, send documents to any email address ending in @sandbox.ziasign.com:

json

{
  "signers": [
    { "name": "Test Signer", "email": "[email protected]" }
  ]
}

Auto-Sign

Simulate a signer completing their fields instantly:

bash

curl -X POST "https://sandbox.ziasign.com/api/v1/documents/{id}/auto-sign" \
  -H "X-Api-Key: $SANDBOX_API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{ "signerEmail": "[email protected]" }'

This triggers the full signing flow: the document status changes, audit trail entries are created, and webhook events fire.

Testing Webhooks

Register a webhook endpoint (use a tool like webhook.site for quick testing)
Create and send a document in the sandbox
Use auto-sign to trigger signing events
Verify your endpoint receives the correct payloads

Sandbox webhook payloads include an extra field:

json

{
  "id": "evt_test_123",
  "type": "document.completed",
  "sandbox": true,
  "data": { ... }
}

Test Payments

When testing billing integration in the sandbox, ZiaSign uses Razorpay as the payment gateway. In sandbox mode, Razorpay provides a test checkout that simulates various payment scenarios:

Card — Use Razorpay's test card numbers (see Razorpay Test Cards)
UPI — Use success@razorpay for successful payments or failure@razorpay for failures
Netbanking / Wallet — Select any option and choose success or failure on the test page

Note: Sandbox payments are never charged. All transactions are simulated.

Going Live Checklist

Before switching to production:

Replace sandbox base URL with production URL
Generate production API keys
Verify webhook signature verification is working
Test error handling for rate limits and timeouts
Review API key scopes — use minimum required permissions
Remove any test/sandbox references from your code

Frequently asked questions

Is the sandbox available to test integrations?

Use the sandbox with test data to validate your integration. Check the current product documentation for availability and limits.

Can I test webhooks in the sandbox?

Yes. Sandbox events trigger webhook deliveries to your registered endpoints, using the same payloads as production with a 'sandbox' flag.

How do I simulate signing?

Send a document to a sandbox email (any @sandbox.ziasign.com address). Use the auto-sign API endpoint to simulate the signer completing their fields instantly.