> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

## Worked sandbox samples

The endpoint list below documents every operation's parameters; this
overlay 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](/guides/using-orbit-samples). 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.orbit.devotel.io/api/v1/sandbox/numbers" \
    -H "X-API-Key: dv_test_sk_YOUR_KEY"
  ```

  ```typescript Node.js theme={null}
  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());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://api.orbit.devotel.io/api/v1/sandbox/pre-launch-checklist" \
    -H "X-API-Key: dv_test_sk_YOUR_KEY"
  ```

  ```typescript Node.js theme={null}
  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());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "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. Errors

Errors follow the `{ error, meta }` envelope. The failure every sandbox
runner hits:

**422 — malformed provisioning body.** A reset or spawn-fixtures call
with a body the sandbox pipeline cannot validate:

```json 422 theme={null}
{
  "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:02:00.000Z"
  }
}
```