Skip to main content
The sandbox lets you exercise the full SuperDial request lifecycle (submit, idempotency, batch scheduling, webhook delivery, signature verification) without placing real phone calls.

​
What’s a sandbox key

Accounts can be provisioned with a sandbox API key/secret pair distinct from any production credentials. Use the sandbox pair when fetching tokens via GET /v1/auth; every request authenticated with the sandbox token is treated as a sandbox request automatically. There is no per-request flag. Ask your account team to provision sandbox credentials if you don’t already have them.

​
What runs the same as production

A sandbox request goes through the identical request-creation flow as a production request:
  • Validation of schemaId and inputs
  • Schema lookup against the schemas provisioned for your account
  • Required-input checks: missing or malformed inputs produce the same INVALID_INPUTS 400 envelope ({"error": "INVALID_INPUTS", "message": "...", "details": {"missingInputs": [...], "invalidInputs": {...}}})
  • internalId idempotency dedup
  • Batch grouping and due-date scheduling against your account’s daily call capacity
  • A real requestId and requestBatchId you can read back with GET /v1/requests/{requestId} and the list endpoint, just like a production request
  • Webhook delivery to your configured URL
  • Response shapes and HTTP status codes: every error code documented in Creating a Request reproduces when using sandbox
Use sandbox to verify error handling, retry logic, idempotency, and webhook ingestion before production traffic.

​
What’s different when using sandbox

For requests that would normally place a phone call to a payer:
  • No phone call is dialed. A call record is still written for traceability, but it never reaches a real outbound phone line.
  • Results are LLM-generated against your schema. SuperDial uses an LLM to produce realistic mock values for every field defined by your schemaId, then feeds those through the same callback path a real call would use.
  • Transcript, recording, and call summary are placeholders. When you fetch the request via GET /v1/requests/{requestId}, you’ll see:
    • transcript: a fixed placeholder line, not a transcript of any real conversation.
    • callSummary: a fixed placeholder sentence.
    • callAuditSummary: a fixed placeholder sentence.
    • recordingDownloadUrl: a signed URL pointing at a placeholder MP3.
  • The request webhook fires as normal. Configure your webhook URL the same way you would for production traffic, and verify the signature with your sandbox API key (see Webhooks → Signature verification).

​
Sandbox webhooks

Sandbox webhooks fire the same way production webhooks do, to the same URL, with the same payload shape:
Sandbox webhooks are signed with your sandbox API key, not with your production key or your webhook secret. Pass the sandbox key to the verification routine for any request created with sandbox credentials. If you set a webhook secret on the portal, it applies to production deliveries only.
After receiving a sandbox webhook, follow the same pattern as production: call GET /v1/requests/{requestId} to fetch the full payload (results, plus the placeholder transcript/summary/recording fields).

​
A typical sandbox test plan

  1. Happy path. POST a single, valid request → assert 200 with requestId → wait for webhook → GET the request → assert state: "SUCCESS" with LLM-generated mock values populating results.
  2. Validation failures. POST with missing schemaId, an inputs field that isn’t an object, missing schema-required inputs, and bad input formats. Confirm your client surfaces the INVALID_REQUEST and INVALID_INPUTS envelopes correctly.
  3. Idempotency. POST the same internalId twice. Confirm the second response returns the same requestId rather than creating a duplicate.
  4. Batch. POST {"requests": [valid, invalid]}. Confirm you get HTTP 207 with a per-entry success body and a per-entry {error, message} envelope, and that your batching/retry logic handles both entries independently.
  5. Webhook signature. Verify the HMAC-SHA256 signature on the incoming webhook body using your sandbox API key.
Every request-side code path runs identically to production, so a passing run of this plan exercises the same logic real traffic will hit.

​
Limits

Sandbox requests count against your account’s daily call capacity for scheduling purposes. If your sandbox account is provisioned with a non-zero limit, batch due-date scheduling can return the same INVALID_REQUEST 400 you’d see in production when capacity runs out (e.g. "Could not schedule all rows within 365 days: N of M rows could not be placed"). Coordinate with your account team if you need a higher sandbox throughput for load testing. Sandbox requestId and requestBatchId values use the same 20-character format as production. Sandbox and live traffic are partitioned:
  • Batches never mix. A sandbox request lands on a sandbox-only batch, so a requestBatchId holds either sandbox requests or live requests, never both.
  • Idempotency is scoped per mode. internalId dedup is keyed by mode, so replaying one of your real record IDs through a sandbox key does not block the later live request that carries the same internalId.