Sandbox & Test Mode

Test mode lets you build and verify your entire integration — uploads, reports, webhooks, and error handling — without processing real documents, consuming production quota, or incurring charges. Every workspace ships with a sandbox enabled by default.

Test vs. live keys

Your dashboard exposes two key pairs. Keys are prefixed so you can tell them apart at a glance, and a request is routed to the environment that matches the key — there is no separate base URL.

Making a sandbox request

Send a sk_test_ key exactly as you would a live key. The response shape is identical to production, so the same client code works in both environments.

curl https://api.heyvisa.com/v1/reports \
  -H "Authorization: Bearer sk_test_8f2c...redacted" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "tourism",
    "destination": "DE",
    "documents": ["doc_test_passport"]
  }'

How sandbox differs from production

• No real OCR. Uploaded files are accepted but not parsed; scoring is driven by deterministic fixtures instead.
• No billing or quota. Sandbox reports never appear on an invoice and never decrement your monthly allowance.
• Isolated data. Test reports, documents, and webhook events live in a separate namespace and are purged automatically.
• Instant results. Async processing resolves in milliseconds so you can exercise webhook flows quickly.

Deterministic fixtures

To exercise specific code paths, reference the reserved test document IDs below instead of uploading a file. Each maps to a fixed analysis outcome so you can assert against red flags and recommendations.

// In sandbox, special document IDs return deterministic fixtures.
{
  "doc_test_passport":        "clean passport, all checks pass",
  "doc_test_passport_expiry": "passport expiring < 6 months (red flag)",
  "doc_test_bank_low":        "bank balance below threshold (red flag)",
  "doc_test_bank_spike":      "unnatural balance spike days before submission"
}