> ## 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.

# E911 emergency drill mode: test your dial plan with 933

> Opt-in, per-organization drill mode that rewrites 933 (and an optional custom training short code) to a safe test destination — so UCaaS rollouts rehearse emergency dialing without touching a live PSAP.

# E911 emergency drill mode

Fire drills for emergency dialing are standard practice on a hosted PBX.
Without drill mode, a 933 dial on Orbit falls through as an unreachable
destination and your dial plan, caller-ID presentation, and desk
notifications have no safe end-to-end rehearsal. Drill mode closes that
gap: it rewrites the dialed digits to a destination you control, so the
full path executes — dial plan, coverage checks, billing, call records,
webhooks — without ringing anything live.

## What drill mode is

Drill mode is a **per-organization, opt-in** setting. While it is off,
nothing changes: 933 is a normal unassigned code, and any custom
training short code you later configure is ignored.

When enabled, two dial strings are rewritten:

| Dial string                             | Behavior                                                                                                                                                                                                                                                            |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `933`                                   | North America's emergency-services **test number**. Carriers that support it answer with an automated PSAP readback. On Orbit it drills to your configured destination.                                                                                             |
| Your **training short code** (optional) | An org-chosen code, 2–16 dialable characters (digits, `+`, `*`, `#`) — for example the short code your PBX dial plan already uses for drills. It drills exactly, with no prefix form, so a real phone number that merely *starts with* the code is never rewritten. |

A rewrite is **rewrite-only routing**: the drill destination is
substituted for the dialed digits and the call proceeds through the
ordinary outbound path — your trunk, the platform's coverage and fraud
checks, standard per-minute billing, a normal call record. Leave
`destination` null and the drill lands on the platform loopback
announcement server, `sip:announce@drill.orbit.devotel.io` — expected
out-of-path behavior, dial-attempt only, no external egress.

## Turn drill mode on and off

Both endpoints are admin-only (organization owner/admin with voice
write access).

### Read the current configuration

```bash cURL theme={null}
curl https://api.orbit.devotel.io/api/v1/voice/emergency-drill \
  -H "X-API-Key: $ORBIT_API_KEY"
```

```json theme={null}
{
  "data": {
    "enabled": true,
    "destination": "sip:drill@pbx.example.com",
    "training_short_code": "9336",
    "drill_test_number": "933",
    "default_destination": "sip:announce@drill.orbit.devotel.io"
  }
}
```

GET always returns `200` with the normalized record — never `404` — so
your dashboard or rollout script can render the empty state directly.
`destination: null` means the platform loopback announcement server.

### Enable or update

```bash cURL theme={null}
curl -X PUT https://api.orbit.devotel.io/api/v1/voice/emergency-drill \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "destination": "sip:drill@pbx.example.com",
    "training_short_code": "9336"
  }'
```

* `destination` accepts an E.164 PSTN number, a SIP URI, or a dialable
  alias (up to 200 characters). Omit it or pass `null` to use the
  platform loopback announcement server.
* `training_short_code` must be 2–16 dialable characters. Setting it to
  `933` is rejected — the built-in test number already drills, so a
  duplicate code is redundant.
* The PUT replaces only the drill record; every other voice setting on
  the organization is preserved.
* Every change is recorded in your audit log.

### Disable — and why disable clears the rest

```bash cURL theme={null}
curl -X PUT https://api.orbit.devotel.io/api/v1/voice/emergency-drill \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'
```

Disabling returns the whole record to the empty state — `destination`
and `training_short_code` are cleared to `null` in the same write. A
stale destination cannot linger across an off/on cycle and silently
re-arm the next time someone flips the toggle. Re-enabling always
starts from a clean slate, and the API reflects that: a GET after the
disable shows all three fields back at their defaults.

## What never gets rewritten

Drill mode can never mask a live emergency call, by construction:

* **Live emergency codes are re-matched inside the drill matcher.**
  Before any rewrite, every candidate input — the dialed string and the
  configured training short code — is run through the same
  emergency-dial matcher that blocks 911, 112, 999, and 000 on every
  outbound call. A candidate that resolves to a live emergency code is
  never rewritten. This is defence-in-depth on top of the platform-wide
  block described in [Emergency calling](/voice/emergency-calling),
  which still fires even in the impossible case a rewrite slipped past.
* **The rewrite runs after your dial plan has been translated.** A dial
  plan entry that translates an input into a live emergency code still
  hits the emergency block; drill mode cannot undo that rejection.
* **The drill destination is re-examined downstream.** The substituted
  destination passes through the same coverage, fraud, and class-of-
  service checks every other outbound call faces.

If an organizer configures a training short code that coincides with a
live emergency code, the config is rejected at save time and declined
again at drill time.

## Failure posture: drill fails open

If the settings read trips on a transient infrastructure error, the
drill check fails **open**: it returns "not configured" and the call
proceeds unrewritten, exactly as drill mode would behave while off. A
transient error can never rewrite a real destination, and it never
surfaces as a call failure. Live emergency codes are unaffected —
their platform block is a hard guard with no dependency on this lookup.

## Run an end-to-end drill

1. **Enable drill mode** with the PUT above. Pick a destination you can
   observe: your PBX's drill announcement point, a conference bridge, an
   internal queue, or leave it null for the platform loopback
   announcement server. Optionally set the training short code your PBX
   dial plan already uses.
2. **Dial 933** (and the training short code, if configured) from each
   surface you ship: a registered desk phone, the browser softphone, an
   agent call flow, your PBX over the SIP trunk.
3. **Verify the full path executed.** The call connects to the drill
   destination, the record appears in **Voice → Calls** with the drill
   destination substituted, your webhook receivers see the normal call
   lifecycle events, and any desk-notification or caller-ID logic you
   wired to emergency-style dials fires.
4. **Verify live codes still block.** From the same surfaces, dial 911
   or 112 and confirm the call is rejected with
   `EMERGENCY_CALLING_NOT_SUPPORTED` — drill mode must never change
   this. If it ever connects, disable drill mode and contact support.
5. **Disable when done.** The disable write clears the destination and
   short code, so the next drill starts from an explicit, reviewable
   configuration instead of a leftover one.

Schedule the drill inside your UCaaS rollout runbook — the same window
where you register the PBX and validate dial plans — and run it again
after any dial plan change that touches emergency-style patterns.

## Related references

* [Emergency calling](/voice/emergency-calling) — the platform block on
  911 / 112 / 999 / 000, the error shape your integration must handle,
  and your operator disclosure obligations.
* [Emergency address (E911)](/numbers/emergency-address) — register the
  per-number dispatchable address; record-keeping that pairs with the
  drill's caller-ID and location verification.
* [E911 glossary entry](/reference/glossary) — platform terminology.
* [Register your PBX on Orbit](/guides/registering-your-pbx-on-orbit) —
  trunk endpoint and registration health, prerequisite for a PBX-side
  drill.
* [CCaaS go-live checklist](/guides/voice-ccaas-go-live-checklist) —
  the rollout runbook this drill belongs in.