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

# Number Timezone and State Resolution

> How Devotel Orbit turns a recipient's E.164 number into an IANA timezone and a USPS state for quiet-hours and calling-window decisions — the lookup chain, its coverage boundaries, and what happens when an area code is unresolvable.

# Number timezone and state resolution

Every quiet-hours and calling-window verdict starts with the same question:
**where is the recipient?** TCPA windows are recipient-local, so before Orbit
can decide whether a call or message is inside the allowed window it has to
derive a timezone — and, for US numbers, a state — from the phone number
itself. This page explains that derivation: what the lookup tables contain,
how they chain together, where coverage stops, and what the verdict becomes
when an area code is unresolvable.

This is an **internal-lookup explainer**, not endpoint documentation — it
describes how the resolution layer underneath
[quiet hours](/compliance/quiet-hours-preview),
[state calling windows](/compliance/state-calling-windows), and the
[recording-consent gate](/compliance/recording-consent) derives its inputs.
Nothing here is a control you configure; the tenant-owned controls sit on
those pages. The resolution layer just answers "what timezone and state does
this number imply" identically for all of them, so a blocked or released
verdict is traceable to one lookup chain rather than per-feature guesswork.

## 1. Why resolution matters for TCPA quiet hours

The federal TCPA voice window — **8 AM–9 PM in the recipient's local time**
— cannot be evaluated without a timezone. A 7:30 PM dial to a Miami number
is legal; the same dial to a Seattle number is not. Quiet-hours evaluation
therefore runs a fixed precedence:

1. An **explicit timezone hint** you pass (per-recipient or per-request) is
   honored first — it always wins over any lookup.
2. For **+1 (NANP) numbers**, the recipient's area code resolves to an IANA
   timezone through the inventory described below.
3. For **non-+1 numbers**, a country-code prefix table supplies a
   best-available timezone.
4. If none of these resolve, the verdict depends on the surface — the
   fail-open / fail-closed split is covered in
   [section 4](#4-coverage-boundaries-and-the-fail-posture).

The same resolved timezone then feeds two different gates:

* **TCPA quiet hours / federal voice window** — the recipient-local hour
  must fall inside the window (default 8 AM inclusive – 9 PM exclusive). The
  hour is computed through ICU/Intl timezone rules, so DST transitions are
  handled correctly on spring-forward and fall-back weekends.
* **State calling windows** — the recipient's USPS state may carry a
  mini-TCPA overlay (shorter hours, a Sunday ban, or both), intersected with
  the federal window most-restrictive-wins. The full overlay table is on
  [US calling windows](/compliance/state-calling-windows).

## 2. Area-code extraction and the timezone inventory

The lookup layer's entry point is area-code extraction: given an E.164
number, strip everything except digits and the leading `+`, then read the
three digits after a `+1` country code. Anything that is not a +1 NANP
shape yields no area code and exits the NANP chain entirely — non-US
recipients are out of TCPA jurisdiction and resolve through the
country-code fallback instead.

Those three digits index the **NANP area-code inventory**: a hand-maintained
map of IANA timezone → assigned area codes, sourced from the NANPA Active
Codes report (the North American Numbering Plan Administrator's monthly
assignment list). Its coverage:

* **US** — all 50 states + DC, including the IANA sub-zones that matter
  for quiet-hours math (Indiana and Michigan each resolve to their own
  zone, Arizona resolves to the no-DST `America/Phoenix`).
* **US territories** — Puerto Rico, US Virgin Islands, Guam, American
  Samoa, Northern Mariana Islands.
* **Canada** — all 10 provinces + 3 territories.

Toll-free area codes (800, 888, etc.) and N11/N00 service codes are
deliberately excluded — they carry no geographic signal, so treating them
as resolvable would fabricate a timezone.

Every gate that needs "area code → timezone" inverts this one inventory
into a per-area-code lookup. Because the inventory is the single source of
truth, the quiet-hours preview, the voice path, and the timezone attached
to audit decisions all resolve identically.

## 3. State resolution for US numbers

For US numbers there is a second projection: **area code → USPS state
code**, a map of roughly 170 single-state assignments built from the same
NANPA data. It exists because two gates need a state, not a timezone:

* **TCPA state calling-window overlays** — seven mini-TCPA states (FL, OK,
  MS, LA, AL, AR, WV) tighten the federal window. Overlays are only looked
  up when the state resolves — the overlay table deliberately stays small
  so your counsel can audit it cheaply.
* **Recording-consent gating** — two-party-consent states (CA, IL, WA, and
  the others listed on the
  [recording consent](/compliance/recording-consent) page) require consent
  from all parties before a call may be recorded.

The state map previously lived as two divergent tables — one biased toward
overlay states, one toward recording-consent states — so the same recipient
could resolve to a state in one gate and to nothing in the other. The
current map is the **union** of both, which is why its coverage is wider
than either gate strictly needs: a TX or NY recipient resolves to a state
even though neither state changes the federal window. The resolved state is
still attached to the decision for telemetry and audit filtering, and the
map gains coverage over time without any gate needing to change.

Multi-state anomalies default to the state with the dominant share of the
area code's footprint; assignments stay single-state by design — the
resolver never returns a list of candidate states.

## 4. Coverage boundaries and the fail posture

Knowing the boundaries tells you what a given number can and cannot
resolve:

| Number shape                                             | Timezone                               | State                                   |
| -------------------------------------------------------- | -------------------------------------- | --------------------------------------- |
| +1 US number, mapped area code                           | IANA zone from the inventory           | USPS code if assigned                   |
| +1 US number, unmapped area code (new NPA not yet added) | Not resolved                           | Not resolved                            |
| +1 Canadian / Caribbean area code                        | IANA zone (Canada is in the inventory) | `null` — no US state, federal-only path |
| Toll-free / non-geographic +1 code                       | Not resolved (excluded by design)      | Not resolved                            |
| Non-+1 (e.g. +44, +33)                                   | Country-code prefix fallback           | `null` — TCPA is US-only                |

**Overlays.** When a city gains an overlay area code, the new NPA resolves
to the same timezone and state as the code it overlays as soon as it is
added to the inventory. Until then it is an unmapped area code with the
fail posture below.

**Timezone ≠ residency.** An area code reflects where a number was
assigned, not where the subscriber lives now. Number portability means a
Miami 305 number can belong to someone in Oregon. When you know a
recipient's actual local timezone, pass it as the explicit
timezone hint — the hint always outranks the area-code lookup.

**Fail-open vs. fail-closed.** The unresolvable case splits by surface:

* **Quiet-hours evaluation and the standalone TCPA window check fail
  open.** An unmapped +1 area code resolves to `unknown_timezone` and the
  send is allowed, with the reason recorded for audit. The alternative —
  blocking every legitimate call to a newly assigned area code — over-blocks
  real traffic.
* **The campaign/dialer voice path under the federal guard fails closed.**
  Because the penalty exposure of an unlawful call outweighs a missed send,
  an unresolvable recipient timezone on that path returns
  `timezone_unresolved` and the call is held. The
  [state calling windows](/compliance/state-calling-windows) page details
  that asymmetry; the fix is to pass an explicit timezone hint.
* **State resolution failing is never fatal.** A `null` state means "no
  overlay applies — federal window unchanged," for both the NANP and the
  non-NANP shapes above. It does not block, and it does not trip the
  timezone fail-closed posture on the voice path.

## 5. Where the resolution feeds

The same lookup chain is consumed by:

* **TCPA quiet-hours decisions** — the boolean allowed/denied evaluation
  behind the send gates and the
  [quiet-hours preview](/compliance/quiet-hours-preview) endpoint. The
  preview returns the resolved timezone and local hour alongside the
  verdict, which is what makes a blocked decision debuggable: you can see
  the exact timezone the gate resolved and compare it against your
  recipient's actual location.
* **Voice-guard timezone resolution** — the campaign/dialer pre-dial gate
  resolves the recipient timezone before any window math; an explicit hint
  is honored first, then the area-code inventory.
* **State calling windows** — the state overlay intersection, as on
  [US calling windows](/compliance/state-calling-windows).
* **Recording-consent gating** — the per-state consent gate, as on
  [recording consent](/compliance/recording-consent).

When you debug a blocked or unexpectedly released quiet-hours verdict,
start from the preview's resolved timezone, then walk this chain: explicit
hint → area-code inventory (or country fallback) → fail posture. One of
those four steps explains every verdict.

## Related

* [Quiet hours preview](/compliance/quiet-hours-preview) — read a verdict
  without sending
* [US calling windows](/compliance/state-calling-windows) — the federal +
  state overlay intersection
* [Recording consent](/compliance/recording-consent) — the per-state
  consent gate
* [TCPA quiet hours and windows](/guides/tcpa-quiet-hours-and-windows) —
  the tenant-owned setup workflow