Special Number Profiles

Special number profiles guarantee that emergency and priority numbers — 911 above all — always route, no matter what else is configured. A number listed in a special-number profile is matched before everything else the switch would normally do to a call, and drops straight into a translation context you dedicate to it.

This exists because ordinary routing has many places a call can be legitimately stopped: toll restriction, concurrent-call caps, feature-code collisions, inbound call blocking. None of those may ever stop an emergency call.

What a special-number match bypasses

When a dialed number matches an entry in the caller’s selected profile, the call skips:

• Feature codes and speed dials — a speed dial or feature code can never shadow an emergency number.
• The normal translation walk — the line/trunk inbound context is not consulted; the call goes directly to the entry’s own translation context.
• Destination screening (toll restriction) — a fully restricted lobby phone still reaches 911.
• Every concurrent-call cap — partition, namespace, line, and trunk limits are all ignored, on both the inbound and outbound side of the call.
• Inbound call blocking policy (STIR/SHAKEN verification actions).

Two things still apply:

• Caller-ID handling runs first — but can never block the call. For trunk-originated calls, the profile’s caller-ID mode still runs, so the identity delivered with an emergency call is normalized where possible. Where an ordinary call would be rejected for a caller ID outside the trunk’s allowed-caller-ids, an emergency call instead degrades: the caller ID is rewritten to the trunk’s primary-caller-id (the trunk’s 911 identity) when one is set, or passed through unscreened when not. A 911 call is never dropped over caller ID.
• The entry’s translation context routes the call. The bypass gets the call into that context; you are responsible for making the context itself deliver the call somewhere that works (see the example below).

Configuration

special-number-profiles is a top-level key. Each profile maps dialed numbers to their handling; today that handling is the translation context the call is dropped into:

special-number-profiles:
  default:
    "911":
      translation-context: emergency
    "933":                       # E911 address readback test number
      translation-context: emergency

Each referenced translation context must exist — the configuration is rejected otherwise.

Selecting a profile

Line profiles and trunk profiles choose a profile by name with the special-number-profile field:

line-profiles:
  standard:
    special-number-profile: default   # may be omitted — empty means "default"
    ...
trunk-profiles:
  wholesale-in:
    special-number-profile: no-intercept
    ...

• An empty selector uses the profile named default.
• If the selected profile doesn’t exist (including a missing default), the special-number stage is a silent no-op and calls route normally. A namespace that declares no special-number-profiles at all is therefore unaffected.
• Naming a profile explicitly that doesn’t exist is a validation error.

Matching is exact, against the raw dialed string

The number keys are compared character-for-character with what the caller dialed, before any translation or normalization. List every variant your callers might produce:

special-number-profiles:
  default:
    "911":
      translation-context: emergency
    "9911":                    # PBX users who dial an access code first
      translation-context: emergency

Quote the number keys

As everywhere in the configuration, unquoted YAML numbers can lose leading digits or be re-formatted. Always write number keys as quoted strings.

The emergency translation context

The context a special number lands in is an ordinary translation context — build it to route unconditionally to your emergency delivery path:

translations:
  emergency:
    "100":
      match:
        - always: true
      modify:
        operations:
          - replace: "911"       # deliver a canonical digit string
      target:
        resource-type: trunk
        resource-id: e911-provider
        failure-treatment: temporary-failure

Keep this context minimal: one always rule, a deterministic rewrite, and a direct trunk or route target. Do not chain it through shared contexts that someone might later edit for other reasons.

Which caller ID is asserted on 911

For a line-originated emergency call, the line’s configured caller ID is the identity your E911 provider uses to find the registered address — lines with an e911 address block must carry a valid US number. For a trunk-originated call, the trunk’s primary-caller-id serves that role. See the emergency calling guide for the address-management workflow and your update obligations.

Worked examples

Standard hosted deployment

Every line and trunk uses the default profile implicitly; 911 and 933 are intercepted for everyone:

special-number-profiles:
  default:
    "911": { translation-context: emergency }
    "933": { translation-context: emergency }

translations:
  emergency:
    "100":
      match:
        - always: true
      target:
        resource-type: trunk
        resource-id: e911-provider
        failure-treatment: temporary-failure

Wholesale trunk that must not intercept

A wholesale customer delivers you traffic that has already had emergency calls handled upstream; 911 arriving on that trunk would be a misdial or test, and must not hit your E911 provider. Point the trunk profile at an empty profile — a profile with no numbers is a valid no-op:

special-number-profiles:
  default:
    "911": { translation-context: emergency }
  no-intercept: {}

trunk-profiles:
  wholesale-in:
    special-number-profile: no-intercept
    inbound-translation-context: from-wholesale
    ...

Lines keep the default interception; the wholesale trunk routes 911 through its ordinary inbound context like any other dialed number (where you can match it explicitly and apply whatever handling your interconnect agreement requires).

Different emergency paths per population

A reseller hosting both US and Canadian tenants in one namespace can route each population’s lines through its own profile:

special-number-profiles:
  us-emergency:
    "911": { translation-context: emergency-us }
  ca-emergency:
    "911": { translation-context: emergency-ca }

line-profiles:
  us-line:
    special-number-profile: us-emergency
    ...
  ca-line:
    special-number-profile: ca-emergency
    ...

Verifying

Because a special-number match bypasses the normal walk, its route-forensics record shows the walk starting directly in the emergency context rather than the line or trunk inbound context. Test emergency routing with your provider’s test number (typically 933) after every change to these profiles or the contexts they reference — never with live 911 calls.