Your first sandbox round trip

The six operations below are the sandbox control plane; this section is the smallest flow that proves your integration end to end before you spend a cent — one key, one send, one webhook, one reset. Every request body below runs unchanged against live mode later; only the key swaps.

1. Mint a test key

In the console: Settings → API Keys → Create key, mode Test. The same mint over the API is POST /api/v1/settings/api-keys with mode: "test" (documented on the Settings page):

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/settings/api-keys" \
  -H "Authorization: Bearer $ORBIT_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-sandbox", "mode": "test" }'

201

{
  "data": {
    "key": "dv_test_sk_2f8KqP4xR7vN1wZc",
    "mode": "test",
    "scopes": null,
    "mintedByRole": "owner",
    "createdAt": "2026-10-16T09:12:34Z"
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-10-16T09:12:34Z"
  }
}

The key value is returned only on this response — store it immediately. From here on, that prefix is the sandbox signal: every request carrying a dv_test_sk_ key runs in test mode with or without the X-Test-Mode header, no carrier is touched, and nothing bills.

2. One canonical send

Send to any E.164 recipient; the trailing digit selects the simulated outcome (§3 below covers the three you will use most; the full catalog is the Magic-numbers playbook). Digit 2 is the happy path:

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/sms" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15005550002",
    "body": "sandbox send"
  }'

200

{
  "data": { "id": "msg_01HZQX7C3M", "status": "test_sent" },
  "meta": {
    "request_id": "req_01HZQX7C4N",
    "timestamp": "2026-10-16T09:13:02Z",
    "test_mode": true
  }
}

Assert meta.test_mode: true in your test harness — it is the only reliable marker that the request actually sandboxed. The header you sent and the key prefix you pulled from config can drift between environments; the response marker cannot. The same send in Node:

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/messages/sms', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_SANDBOX_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ to: '+15005550002', body: 'sandbox send' }),
})
const body = await res.json()
if (body.meta.test_mode !== true) throw new Error('expected sandbox, got live')

3. Magic numbers — the recipient picks the outcome

The three magic numbers you will reach for most, one send each:

Outcome	Magic number	Webhook sequence
Delivered immediately	`+15005550002`	`sent` → `delivered` (~50 ms)
Handset reject (DLR failed)	`+15005550003`	`sent` → `undelivered` (~1 s)
Carrier / pre-submit error	`+15005550004`	`failed` (no `sent` ACK)

cURL — delivered

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/sms" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+15005550002", "body": "delivered scenario" }'

200

{ "data": { "id": "msg_01HZQX9D5P", "status": "test_sent" }, "meta": { "request_id": "req_01HZQX9D6Q", "timestamp": "2026-10-16T09:14:11Z", "test_mode": true } }

cURL — DLR failed

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/sms" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+15005550003", "body": "undelivered scenario" }'

200

{ "data": { "id": "msg_01HZQX9E6R", "status": "test_sent" }, "meta": { "request_id": "req_01HZQX9E7S", "timestamp": "2026-10-16T09:14:26Z", "test_mode": true } }

cURL — carrier error

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/sms" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+15005550004", "body": "failed scenario" }'

200

{ "data": { "id": "msg_01HZQX9F7T", "status": "test_sent" }, "meta": { "request_id": "req_01HZQX9F8V", "timestamp": "2026-10-16T09:14:41Z", "test_mode": true } }

All three sends return test_sent; the simulated receipts never mutate the stored row. They arrive only on the webhook stream (§4 below), replaying the same intermediate → terminal sequence a real carrier produces — the 4 case arrives as a lone failed with no preceding sent ACK, which is exactly the branch your retry logic must not get wrong.

4. The sandbox-tagged DLR webhook

Orbit posts the same message.status envelope it posts in live mode to the sandbox webhook URL you set in the console, tagged so your receiver can tell test traffic apart:

Webhook POST — message.status

{
  "id": "evt_01HZQXA1B2",
  "type": "message.status",
  "created_at": "2026-10-16T09:14:12Z",
  "data": {
    "id": "msg_01HZQX9D5P",
    "to": "+15005550002",
    "status": "delivered",
    "state_class": "terminal",
    "is_terminal": true,
    "sandbox": true,
    "test_mode": true
  }
}

Verify the X-Devotel-Signature header, ack within 30 seconds, and dedupe on id — retries are expected. The verifying receiver (Node and Python) is worked in the Sandbox API cookbook; per-digit receipt timings stay canonical at magic numbers.

5. Reset the workspace

When a test run leaves debris, wipe the sandbox back to a clean slate in one call (the same operation worked with its full envelope as §6 below):

cURL

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

200

{
  "data": {
    "contacts_deleted": 12,
    "conversations_deleted": 4,
    "messages_deleted": 37,
    "numbers_released": 2
  },
  "meta": {
    "request_id": "req_01HZQXB2C3",
    "timestamp": "2026-10-16T09:20:05Z",
    "test_mode": true
  }
}

Contacts, conversations, messages, and sandbox-provisioned numbers are gone; your API keys, saved test recipients, and the sandbox webhook URL survive — they are org settings, not workspace data. Live-mode requests are refused with 403 SANDBOX_ONLY before a single row changes. Ready to cut over to real traffic? The pre-launch checklist (§2 in the per-operation section below, and its endpoint page) returns readyForLaunch: true once every gate passes, and sandbox and test mode walks the live-key graduation.

Worked sandbox samples

The generated endpoint list documents every operation’s parameters; this section walks a sandbox environment the way a pre-launch integration checklist actually uses it: list the sandbox numbers → read the pre-launch checklist → handle a provisioning reset. Success envelopes are { data, meta }, error envelopes { error, meta } — see How to read a worked sample. A sandbox (dv_test_sk_*) key drives the whole pipeline, and a reset always leaves your tenant with the clean fixture set the checklist expects. Every response carries meta.request_id. Quote the request id when you report a provisioned number that vanishes between calls or a checklist item that flips mid-run.

1. List sandbox numbers

GET /api/v1/sandbox/numbers returns the sandbox phone numbers provisioned for your tenant — the pool the rest of the sandbox surfaces send/receive from. Use this to verify the provision-numbers route below landed before you spawn fixture contacts.

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

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/sandbox/numbers",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "numbers": [
      {
        "id": "num_8fb2d1b7c00c4ec9",
        "phone_number": "+14155552671",
        "capabilities": ["voice", "sms"],
        "provisioned_at": "2026-08-26T11:55:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_snd_numbers",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

2. Read the pre-launch checklist

GET /api/v1/sandbox/pre-launch-checklist returns the readiness items a launch gate evaluates — provisioned numbers, expected fixture contacts, inbound and outbound smoke-paths. Use it to decide when the tenant is a candidate for the live dv_live_sk_* cutover.

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

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/sandbox/pre-launch-checklist",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "items": [
      { "name": "numbers-provisioned", "ok": true },
      { "name": "inbound-reachability", "ok": true },
      { "name": "outbound-smoke", "ok": false }
    ]
  },
  "meta": {
    "request_id": "req_snd_checklist",
    "timestamp": "2026-08-26T12:01:00.000Z"
  }
}

3. Provision test numbers

POST /api/v1/sandbox/provision-numbers mints deterministic fictional +1(555)01XX numbers for your sandbox tenant — the pool the rest of the surfaces send and receive from. Assert the returned count before you spawn fixture contacts that depend on these numbers.

curl -X POST "https://api.orbit.devotel.io/api/v1/sandbox/provision-numbers" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/sandbox/provision-numbers",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
  },
);
console.log(await res.json());

200

{
  "data": {
    "numbers": [
      {
        "id": "num_8fb2d1b7c00c4ec9",
        "phone_number": "+15555550101",
        "capabilities": ["sms", "voice"]
      }
    ],
    "count": 1
  },
  "meta": {
    "request_id": "req_snd_provision",
    "timestamp": "2026-08-26T12:02:00.000Z"
  }
}

The body is optional — omit it to mint the default batch. Pass { count, country_code, capabilities } to scale the pool deterministically.

4. Inject a simulated inbound message

POST /api/v1/sandbox/inbound pushes a synthetic mobile-originated message into the tenant inbox — the receive half of the Virtual Phone. Use it to exercise auto-responders, STOP keywords, or inbox routing without hand-forging a provider webhook.

curl -X POST "https://api.orbit.devotel.io/api/v1/sandbox/inbound" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "+15005550101", "body": "hi"}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/sandbox/inbound",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ from: "+15005550101", body: "hi" }),
  },
);
console.log(await res.json());

200

{
  "data": {
    "message_id": "sbx_01J2M8XQJ5ABCDE",
    "conversation_id": "cvb_01J2M8XQJ9KLMN0",
    "created_conversation": true,
    "created_contact": false,
    "channel": "sms",
    "from": "+15005550101",
    "to": "+15555550101",
    "body": "hi"
  },
  "meta": {
    "request_id": "req_snd_inbound",
    "timestamp": "2026-08-26T12:03:00.000Z"
  }
}

The response returns the committed row IDs — assert created_conversation confirms the inbox list has a new thread. created_contact flips to true the first time a from appears.

5. Spawn fixture contacts

POST /api/v1/sandbox/spawn-fixture-contacts seeds deterministic contacts (and optionally conversations) so a probe can iterate through a non-empty inbox list repeatedly. Reset between runs to leave them idempotent.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/sandbox/spawn-fixture-contacts" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/sandbox/spawn-fixture-contacts",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
  },
);
console.log(await res.json());

200

{
  "data": {
    "contacts": [
      {
        "id": "con_012abc3456789",
        "name": "Sandbox Alice",
        "phone_number": "+15555550101"
      },
      {
        "id": "con_012abc3456790",
        "name": "Sandbox Bob",
        "phone_number": "+15555550102"
      }
    ],
    "conversations_created": 2
  },
  "meta": {
    "request_id": "req_snd_contacts",
    "timestamp": "2026-08-26T12:04:00.000Z"
  }
}

with_conversations defaults to true; pass it as false when a probe just needs the contact rows.

6. Reset the sandbox

POST /api/v1/sandbox/reset wipes the tenant’s messages, conversations, and contacts, and releases every number the sandbox provisioned for you. Run it when a test pass needs a clean slate — after a reset the pre-launch checklist above reads exactly the fixture set a fresh sandbox starts with, so the probe sequence is deterministic from the first call.

curl -X POST "https://api.orbit.devotel.io/api/v1/sandbox/reset" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/sandbox/reset",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
  },
);
console.log(await res.json());

200

{
  "data": {
    "messages_deleted": 42,
    "conversations_deleted": 7,
    "contacts_deleted": 10,
    "numbers_released": 3
  },
  "meta": {
    "request_id": "req_snd_reset",
    "timestamp": "2026-08-26T12:05:00.000Z"
  }
}

The reset takes no body. Each counter reports how many rows that run removed — assert numbers_released before you provision again when a test depends on the pool being empty.

7. Errors

Errors follow the { error, meta } envelope. The failure every sandbox runner hits: 422 — malformed provisioning body. The reset call above with a body the sandbox pipeline cannot validate (Content-Type set to JSON and a non-JSON payload, or an unexpected JSON shape on the provisioning endpoints in the same namespace):

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Expected a JSON body for the sandbox provisioning call.",
    "status": 422
  },
  "meta": {
    "request_id": "req_snd_err",
    "timestamp": "2026-08-26T12:06:00.000Z"
  }
}

This overlay shows each op’s concrete envelope once; the guide-level Sandbox API cookbook and Magic-numbers playbook walk the full request/response pair across all six supported languages.

API Reference

All Endpoints

Your first sandbox round trip