Skip to main content

​
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, state calling windows, and the recording-consent gate 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.
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.

​
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 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: 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 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 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.
  • Recording-consent gating — the per-state consent gate, as on 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.