Sandbox API Cookbook

Every sandbox route the sandbox overview catalogs, shown as a runnable request/response pair. The sandbox and test mode guide walks the concepts end to end; this page is the recipe sheet you keep open while you script against the sandbox. All examples use your sandbox secret key, exported as an environment variable:

export ORBIT_SANDBOX_KEY="dv_test_sk_…"

1. Setup — what puts a request in sandbox mode

Any one of these three signals activates sandbox mode; the mutation routes below gate on them before touching data. You usually need exactly one. Signal A — a sandbox API key (the normal one for scripts):

curl https://api.orbit.devotel.io/api/v1/sandbox/numbers \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY"

Signal B — a sandbox organization. Every account ships with a paired sandbox org; pick it in the console organization switcher and an API key minted on that org is implicitly sandbox-scoped. Signal C — the X-Test-Mode: true header (dashboard sessions only — the Test/Live toggle sets it for you):

curl https://api.orbit.devotel.io/api/v1/sandbox/numbers \
  -H "X-API-Key: $ORBIT_KEY" \
  -H "X-Test-Mode: true"

GET endpoints like /sandbox/numbers and /sandbox/pre-launch-checklist do not gate on the signal (any authenticated key can read them), but every POST below refuses a non-sandbox context with 403 SANDBOX_ONLY. See the failure modes section for the envelope.

2. Provision test numbers

Mint deterministic fictional +1 (555) 01XX numbers into your sandbox inventory. No carrier is touched — the rows write straight into your tenant with provider: "sandbox" and monthly_cost: "0.0000".

curl -X POST https://api.orbit.devotel.io/api/v1/sandbox/provision-numbers \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "count": 5 }'

{
  "data": {
    "count": 5,
    "numbers": [
      {
        "id": "number_…",
        "phone_number": "+15550137",
        "country_code": "US",
        "capabilities": ["sms", "voice"],
        "provider": "sandbox",
        "number_type": "local",
        "status": "active",
        "monthly_cost": "0.0000"
      }
    ]
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

Bounds and behaviour:

count caps at 25 per call (MAX_PROVISION_NUMBERS); country_code (2-letter, default US) and capabilities (a non-empty subset of sms / voice / mms) are optional.
The numbers are deterministic per tenant — a reset-then-provision run gets the identical inventory, and re-provisioning the same count is idempotent (the deterministic number is the conflict key, so it upserts rather than duplicates).

Rejections: count above 25 (or 0, or non-integer) fails validation with a 400; an omitted body defaults count to 5.

3. Spawn fixture contacts

Seed deterministic contacts (Ada Lovelace, Grace Hopper, …) so your inbox, auto-responder, and segment flows have something to work against. Each fixture’s phone ends in the trailing digit of one of the 10 magic numbers, so every delivery scenario has a ready-made recipient.

curl -X POST https://api.orbit.devotel.io/api/v1/sandbox/spawn-fixture-contacts \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "count": 3, "with_conversations": true }'

{
  "data": {
    "conversations_created": 3,
    "contacts": [
      {
        "id": "contact_…",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "display_name": "Ada Lovelace",
        "email": "ada.lovelace.…@sandbox.orbit.test",
        "phone": "+15005550001",
        "company": "Analytical Engines",
        "lifecycle_stage": "lead",
        "tags": ["sandbox-fixture"]
      }
    ]
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

Bounds and behaviour:

count caps at 50 per call (MAX_FIXTURE_CONTACTS); an omitted body defaults to 10 contacts.
with_conversations defaults to true. With it on, each contact gets one open inbound SMS conversation carrying a greeting message, so the Inbox has a live thread immediately. Set it to false when you want bare contacts.
Fixture contacts are tagged sandbox-fixture, which is what POST /sandbox/reset sweeps away with the rest of the workspace.

4. Virtual Phone — inject an inbound message

Simulate the handset replying to you: the message lands in your sandbox inbox exactly like a real inbound provider webhook, without forging one. Use it to drive auto-responders, STOP keywords, inbox routing, and the unassigned-notification path.

curl -X POST https://api.orbit.devotel.io/api/v1/sandbox/inbound \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15005550002",
    "channel": "sms",
    "body": "STOP",
    "contact_name": "QA Handset"
  }'

{
  "data": {
    "message_id": "msg_…",
    "conversation_id": "conv_…",
    "contact_id": "contact_…",
    "contact_name": "QA Handset",
    "channel": "sms",
    "from": "+15005550002",
    "to": "sandbox",
    "body": "STOP",
    "media_url": null,
    "status": "received",
    "created_contact": true,
    "created_conversation": true
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

Request rules:

channel accepts only sms, mms, or whatsapp (default sms).
The call is rejected (400 VALIDATION_ERROR) unless it carries a non-empty body or a media_url (an https:// URL, max 2048 chars, for an MMS / WhatsApp media message). body caps at 1600 characters.
from must be E.164; to is optional (defaults to the sandbox sentinel). contact_name sets the display name on a freshly created contact.
Repeat injections from the same sender on the same channel thread into the open conversation (created_conversation: false), matching the real inbound path.

The response’s created_contact / created_conversation flags tell you whether this injection minted rows or threaded into existing ones — the same distinction the live recorder reports.

5. Reset the sandbox

Wipe the sandbox workspace back to a clean slate in one transaction — every contact, conversation, and message, plus every sandbox-provisioned number released. Your API keys, saved test recipient, and sandbox webhook URL survive (they are org settings, not workspace data).

curl -X POST https://api.orbit.devotel.io/api/v1/sandbox/reset \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY"

{
  "data": {
    "contacts_deleted": 12,
    "conversations_deleted": 7,
    "messages_deleted": 19,
    "numbers_released": 5
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

Zero counts mean the workspace was already clean — reset reports what it actually deleted. Real-provider numbers (which a sandbox workspace should never hold) are untouched.

6. Magic numbers catalog

The 10 delivery-state scenarios, keyed by the recipient’s trailing digit. Any authenticated key reads it; the dashboard’s magic-number table renders exactly this list.

curl https://api.orbit.devotel.io/api/v1/sandbox/numbers \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY"

{
  "data": {
    "docs_url": "https://docs.orbit.devotel.io/sandbox/magic-numbers",
    "numbers": [
      {
        "trailing_digit": "1",
        "example_e164": "+15005550001",
        "status": "submitted",
        "label": "Submitted only",
        "description": "Carrier accepts the message and returns an ACK, but never reports a final delivery state.",
        "fires_dlr": false,
        "dlr_latency_ms_min": 0,
        "dlr_latency_ms_max": 0,
        "rewrite_footer": null
      },
      {
        "trailing_digit": "2",
        "example_e164": "+15005550002",
        "status": "delivered",
        "label": "Delivered (happy path)",
        "description": "Carrier accepts and the handset reports delivered within ~50 ms.",
        "fires_dlr": true,
        "dlr_latency_ms_min": 0,
        "dlr_latency_ms_max": 100,
        "rewrite_footer": null
      }
    ]
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

Target sends at these numbers to drive your retry, dead-letter, and alerting branches; the full digit-to-scenario semantics live at magic numbers.

7. Pre-launch checklist

The shared five-step go-live gate — callable with either a live or sandbox key, and always evaluated against your live workspace so both contexts agree on the result.

curl https://api.orbit.devotel.io/api/v1/sandbox/pre-launch-checklist \
  -H "X-API-Key: $ORBIT_SANDBOX_KEY"

{
  "data": {
    "readyForLaunch": false,
    "isSandbox": true,
    "sandboxPairId": "org_…",
    "items": [
      { "id": "sandbox_workspace_ready", "status": "complete" },
      { "id": "live_workspace_ready", "status": "pending" },
      { "id": "sandbox_token_minted", "status": "complete" },
      { "id": "integration_exercised", "status": "complete" },
      { "id": "ip_allowlist_configured", "status": "pending" }
    ]
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

Parse readyForLaunch — it flips to true only when every item reports status: "complete". Wire it into launch scripts to fail CI on an unfinished gate; the pre-launch checklist reference explains each item.

8. Failure modes

The gate every mutation route enforces — shown here with a live key:

curl -X POST https://api.orbit.devotel.io/api/v1/sandbox/reset \
  -H "X-API-Key: $ORBIT_LIVE_KEY"

{
  "error": {
    "code": "SANDBOX_ONLY",
    "message": "Sandbox state-control endpoints require a sandbox API key (dv_test_sk_…) or a sandbox organization. Refusing to mutate a live tenant.",
    "status": 403
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

Other errors you will hit, and what they mean:

HTTP	Code	Cause
`403`	`SANDBOX_ONLY`	A POST ran in a live context — activate one of the three setup signals
`400`	`VALIDATION_ERROR`	Bad body: `count` out of range, non-E.164 `from`, missing `body` + `media_url`, bad `channel`
`401`	`UNAUTHORIZED`	Missing or invalid API key
`429`	`RATE_LIMITED`	Over the 60 req/min per-tenant authenticated-write budget (all sandbox mutations share it) — back off to the next minute window

Honest limits

Number inventory is fictional. Provisioned numbers come from the NANP-reserved +1 (555) 01XX range and carry provider: "sandbox" — they can send to and receive from other sandbox fixtures only. No carrier ever sees them.
Channels that still run live. Only SMS, MMS, WhatsApp, and Email short-circuit in test mode. Voice, RCS, push, and fax still hit their real stacks and bill normally even with a sandbox key — route those tests at +1 555 numbers to avoid carrier fees, and expect no sandbox inbound support for them (the endpoint accepts only the three messaging channels above).
Sandbox POSTs write real rows into your sandbox tenant. Reset is the only cleanup — there is no per-route undo.
Rate budget is shared. Console clicks on the Developer → Sandbox page and your scripts draw from the same 60 req/min write limit.

Sandbox overview — the concepts, activation signals, and constants this cookbook exercises
Sandbox and test mode — the end-to-end walkthrough including magic-number sends and deterministic verify codes
Sandbox dashboard walkthrough — the console equivalent of every recipe here
Magic numbers — the 10 delivery scenarios in full
Pre-launch checklist — the five-step gate, item by item
Developer API playground — run these calls from the in-console request console instead of curl

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Sandbox API: worked examples — provision, fixtures, Virtual Phone, reset

Sandbox API Cookbook

1. Setup — what puts a request in sandbox mode

2. Provision test numbers

3. Spawn fixture contacts

4. Virtual Phone — inject an inbound message

5. Reset the sandbox

6. Magic numbers catalog

7. Pre-launch checklist

8. Failure modes

Honest limits

​Sandbox API Cookbook

​1. Setup — what puts a request in sandbox mode

​2. Provision test numbers

​3. Spawn fixture contacts

​4. Virtual Phone — inject an inbound message

​5. Reset the sandbox

​6. Magic numbers catalog

​7. Pre-launch checklist

​8. Failure modes

​Honest limits

​Related pages

Sandbox API Cookbook

1. Setup — what puts a request in sandbox mode

2. Provision test numbers

3. Spawn fixture contacts

4. Virtual Phone — inject an inbound message

5. Reset the sandbox

6. Magic numbers catalog

7. Pre-launch checklist

8. Failure modes

Honest limits

Related pages