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

# Recipient timezone resolution for quiet hours

> One map for how Orbit picks the timezone your quiet-hours gate evaluates in — the NANP area-code map, the country-prefix map, your IANA override, the org default timezone, and the unknown-timezone policy that decides whether an unresolved recipient fails open or fails closed.

# Recipient timezone resolution for quiet hours

Every quiet-hours decision — org gate, campaign fallback window, TCPA
voice guard — is computed against the recipient's local clock. That
means the whole posture stands or falls on one question: **which IANA
timezone did the platform use for this recipient?** The individual
guides each cover a slice of the answer. This page is the single map:
the resolution chain, what happens when it resolves nothing, and how to
steer it with per-call overrides and org-level policy.

## The resolution chain

Resolution runs fewer steps than there are channels, but each step is
the same for every channel. First match wins:

1. **An explicit IANA hint** — a `timezone_override` on the preview call,
   or a `recipientTimezone` carried on the send — beats every automatic
   source below.
2. **The NANP area-code map** — for +1 numbers, the area code (and, in
   split states, the full prefix) maps to a single IANA zone such as
   `America/Los_Angeles` or `America/New_York`. This is the step that
   usually answers for US recipients.
3. **The country-prefix map** — for non-NANP numbers, the E.164 country
   code maps to a representative IANA zone (a capital-city zone for
   well-known markets). European, Asian, and Latin-American markets
   resolve here most of the time.
4. **The org default timezone** — for recipients without a usable
   number (email addresses, push tokens), the timezone you set on your
   organization supplies the clock.
5. **Unresolved** — when none of the above produced a zone, the
   recipient lands on your org's `unknown_timezone_policy`, below.

A relocated US mobile number resolves by its area code, not by where
the recipient sleeps — if your CRM carries better knowledge, override
it (next section) rather than relaxing the policy.

## When nothing resolves: fail-open vs fail-closed

The `unknown_timezone_policy` is one of three values, and it is a
tenant-owned control you set on your org:

| Policy           | Behaviour                                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `skip` (default) | Allow the send — fail open. The right posture for recipients outside US jurisdiction.                                   |
| `deny`           | Hold the send. Non-voice channels return `422 QUIET_HOURS_TIMEZONE_UNKNOWN`; voice returns `422 TCPA_TIMEZONE_UNKNOWN`. |
| `enforce_utc`    | Evaluate the window against UTC — a deterministic answer regardless of the recipient.                                   |

Set it in the dashboard under **Settings → Voice**, or in the
`quiet_hours` block of organization settings over the API (see
[quiet hours configuration](/guides/quiet-hours-configuration) for the
scoped `PATCH` surface and the whole-document-replace warning).

**The one fail-closed-by-default case.** The controls above are yours
to tune. The sole exception is the TCPA federal voice dial window for
US recipients: campaign and dialer voice to a +1 recipient that
resolves no timezone is blocked regardless of your policy, with no
tenant-side opt-out — that federal wire is the only guard the platform
owns outright. Every other channel, and ad-hoc voice to non-US
recipients, follows your configured policy (defaulting to fail-open
`skip`). The
[quiet-hours preview](/compliance/quiet-hours-preview) enumerates the
full `reason` set per channel — `unknown_timezone_skip` and
`unknown_timezone_deny` are the two this policy produces.

Write the org default timezone the same way — it feeds step 4 of the
chain, mostly for email and push recipients that carry no phone
number.

## Overriding per call: `timezone_override`

Preview calls accept a `timezone_override` parameter, and send paths
accept a `recipientTimezone` hint. Both take an IANA name
(`America/Phoenix`, not `UTC-7`) and win over every automatic source:

```bash theme={null}
curl -G "https://api.orbit.devotel.io/api/v1/compliance/quiet-hours/preview" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  --data-urlencode "phone=+14805551234" \
  --data-urlencode "channel=sms" \
  --data-urlencode "timezone_override=America/Phoenix"
```

The response's `local_timezone` field tells you which source won —
echo it in your rollout checklist before launch and compare it against
what your CRM expected. Field-by-field semantics for the whole response
live on the
[quiet-hours preview](/compliance/quiet-hours-preview) page.

## DST is a resolution problem, not a window problem

The window is always checked in recipient-local time, so the IANA zone
is the thing to verify. Two recurring pitfalls, both resolved by
getting the zone right:

* **Arizona and Hawaii never observe DST** — a contact field stamped
  "Mountain" tells you nothing about Phoenix's offset today. Resolve
  the zone and use it; the math follows the IANA database through
  whichever offset is current.
* **Crossover nights change UTC waits, not wall-clock windows** —
  resolves to the same zone before and after. Recheck around each
  crossover by re-running the preview and confirming the zone name
  stays the expected IANA name.

Both pitfalls are worked through in
[quiet hours across DST](/guides/quiet-hours-dst-crossover) — including
the Arizona/Hawaii special cases, worked timelines for the 2026
March 8 / November 1 crossover dates, and the pre-launch preview
procedure.

## See also

* [Quiet-hours preview](/compliance/quiet-hours-preview) — response
  fields, per-channel semantics, worked calls
* [Quiet hours configuration](/guides/quiet-hours-configuration) — the
  org gate, campaign fallback, and the `unknown_timezone_policy` write
  surface
* [US state calling windows](/compliance/state-calling-windows) — the
  federal wire and state overlays the voice path intersects
* [Quiet hours across DST](/guides/quiet-hours-dst-crossover) — the
  crossover-night verification runbook