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

# Org-wide business hours and holiday calendar defaults

> Set the org-level company-hours schedule and holiday calendar once, let every ACD queue, inbound route, and auto-attendant inherit it, and override per queue, per route, or per field when one surface needs its own schedule.

Org-wide business hours (also called company hours) are the schedule you set once for the whole organization. Every ACD queue, inbound route, and auto-attendant that has not declared its own schedule inherits them — so "the office is closed on Friday" is one edit, not fifteen. Set an org-level holiday calendar beside the hours and every inheriting surface treats those dates as closed even when the weekday window says open.

This page covers what the org default is, who can change it, how to set it over the API, where the inheritance lands, and one queue that inherits then overrides.

**Base path:** `/api/v1/organization/business-hours`

**Authentication:** API key or dashboard session. Reads are open to any org member; writes need an owner or admin role.

***

## 1. What the org-level hours and holiday calendar are

Orbit resolves an inbound call's schedule in three layers, per field. Each of `business_hours` and `holiday_calendar_id` resolves independently — a local value on one field never suppresses inheritance of the other:

1. **The surface's own value** — the queue, route, or attendant set this field itself → that value wins.
2. **The org default** — the surface left the field unset → it inherits the org-wide value from this page.
3. **No gate** — neither layer set the field → no restriction; calls are never gated by a schedule that was never configured.

Three surfaces consume the org default:

| Surface                              | Inherits when                                                | Sets its own on                                                          |
| ------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------------------ |
| **ACD queues**                       | `business_hours` or `holiday_calendar_id` unset on the queue | the queue's own schedule fields                                          |
| **Inbound routes** (per-DID routing) | unset on the route                                           | the route's `business_hours` / `holiday_calendar_id` on the routing rule |
| **Auto-attendants**                  | unset on the attendant                                       | the attendant's schedule on the route it fronts                          |

Two properties to build on:

* **Per-field independence.** A queue can set its own weekday hours and still inherit the org holiday calendar, or the reverse. Override one field, inherit the other.
* **Fail-open evaluation.** A missing, unreadable, or misconfigured schedule never blocks a call — the surface behaves as if no gate fired. A bad org default degrades to "no restriction," it does not lock your callers out.

The [holiday calendars guide](/guides/voice-calendars) covers authoring the calendar itself and the holiday-beats-open-window precedence; this page is only about where the org default lives and who inherits it.

## 2. Who can read and who can change it

* **Read (`GET`)** — any member of the organization. Reading the company hours is a normal operator action, so the endpoint answers for every role.
* **Write (`PUT`)** — owner or admin only, matching the rest of the organization configuration writes. Members with a lower role get a 403 on write.

Every successful write lands in the [audit log](/guides/audit-log) with the fields that changed, so an org hours change is traceable to the admin who made it.

## 3. Set company hours and holiday dates

The endpoint is diff-submit: send only the fields you want to change. An omitted field keeps its stored value; an explicit `null` clears that org default.

`business_hours` accepts the same two shapes the per-route scheduler accepts:

* **Single window** — `{ days, start, end, timezone }`: one window applied across the listed days. Days can be numbers (`0` = Sunday … `6` = Saturday) or lowercase day names (`"mon"`, `"tue"`, …), and omitting `days` means every day.
* **Per-day** — `{ timezone, mon, tue, ... }`: each weekday maps to `{ open, close }` or `null` (closed that day).

`holiday_calendar_id` must reference a holiday calendar owned by your organization — the id from **Voice → Calendars** (see [holiday calendars](/guides/voice-calendars)). An id from anywhere else answers `422`.

```bash cURL theme={null}
curl -X PUT "https://api.orbit.devotel.io/api/v1/organization/business-hours" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "business_hours": {
      "days": ["mon", "tue", "wed", "thu", "fri"],
      "start": "09:00",
      "end": "17:30",
      "timezone": "America/New_York"
    },
    "holiday_calendar_id": "calendar_01HX..."
  }'
```

Read back the resolved defaults:

```bash cURL theme={null}
curl "https://api.orbit.devotel.io/api/v1/organization/business-hours" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

```json theme={null}
{
  "data": {
    "business_hours": {
      "days": [1, 2, 3, 4, 5],
      "start": "09:00",
      "end": "17:30",
      "timezone": "America/New_York"
    },
    "holiday_calendar_id": "calendar_01HX..."
  }
}
```

An organization that has never set a default reads back `{ "business_hours": null, "holiday_calendar_id": null }` — no gate anywhere inherits anything until you set one. To clear just the holiday tie while keeping the hours, send `{ "holiday_calendar_id": null }`.

<Tip>
  Keep the timezone in the org default aligned with your **Settings → General** workspace timezone ([general settings](/guides/organization-general-settings)). The schedule timezone is explicit per schedule, so a mismatch resolves — it is just confusing to read later.
</Tip>

## 4. Where the cascade lands

Because inheritance is per field, ten minutes of setup is: set both org fields once, then touch only the surfaces that genuinely differ.

| What you want                                                           | What you do                                                                                                        |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Every queue, route, and attendant follows company hours                 | Set the org default once; leave surfaces unset                                                                     |
| One queue works weekends                                                | Inherit hours org-wide; override that one queue's `business_hours`                                                 |
| The support queue ignores company holidays but inherits everything else | Set `holiday_calendar_id` on that queue (even to a deliberately empty calendar) — a local value blocks inheritance |
| The main DID's inbound route keeps its routing but takes company hours  | Leave the route's schedule fields unset; the route config stays untouched                                          |

The queue case in practice — one queue that inherits, then overrides:

**Inherit.** Create the queue with no schedule fields. It follows the org company hours and holidays automatically; nothing to maintain on the queue itself when the org schedule changes.

**Override.** Give it its own window and its inheritance of that field ends:

```bash cURL theme={null}
curl -X PUT "https://api.orbit.devotel.io/api/v1/voice/queues/queue_01h..." \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "business_hours": {
      "timezone": "America/New_York",
      "mon": { "open": "08:00", "close": "20:00" },
      "tue": { "open": "08:00", "close": "20:00" },
      "wed": { "open": "08:00", "close": "20:00" },
      "thu": { "open": "08:00", "close": "20:00" },
      "fri": { "open": "08:00", "close": "20:00" },
      "sat": { "open": "10:00", "close": "16:00" }
    }
  }'
```

This queue now runs 08:00–20:00 weekdays plus Saturday 10:00–16:00 and still inherits the org holiday calendar — the per-day shape with `sun` absent marks Sunday closed, and `holiday_calendar_id` was never touched on the queue so the org calendar keeps applying.

## 5. Two worked examples, both directions

**Org-wide, cascaded down.** A rotating on-call team wants weekends off everywhere. PUT the org default `business_hours` to the per-day shape with `sat: null, sun: null`. Every queue, route, and attendant without a local override now treats weekends as closed; callers land on the fallback path (voicemail, a closed message, an IVR branch) per that surface's closed action. One edit, whole org.

**Surface-level override.** The escalation queue must stay reachable on Saturday. Set the org default closed on weekends as above, then PUT that one queue's `business_hours` with `sat: { open: "09:00", close: "13:00" }`. The whole org still inherits the weekend-closed org default; this one queue opens Saturday morning because its local value wins — and it still inherits the org holiday calendar, because that field is unset locally.

## 6. Production checklist

* **Inheritance is per field, not per surface.** Overriding hours does not stop holiday inheritance (and vice versa). Check both fields when a surface behaves unexpectedly — a local `holiday_calendar_id` set months ago will keep blocking org-holiday inheritance even after the hours were overridden.
* **Holiday beats open hours.** A date on the inherited org calendar closes the surface even inside an otherwise-open weekday window. Model genuine holidays there; a calendar that accidentally lists a normal Tuesday closes everything that inherits it.
* **DST is handled per timezone.** Both hours and calendar timezones are IANA zones, so the gate re-derives "today" correctly across daylight-saving transitions — no copy change needed, but any surface that pinned a fixed offset (avoidable only by not using the timezone field) would drift. Prefer the zone name everywhere.
* **Clear with `null`, not omit.** Sending `{}` or omitting a field is a no-op; send the field explicitly set to `null` to remove an org default.
* **422 on the calendar id means wrong-org or missing.** The holiday calendar must belong to your organization; re-check the id from the calendars list before retrying.
* **Fallback path still needs configuring.** Inheriting a "closed" decision only helps if the surface's closed action (voicemail, IVR branch, callback offer) points somewhere sensible. The org default decides *when* a surface is closed; each surface's own fallback decides *what happens* then.

## See also

* [Holiday calendars for inbound voice](/guides/voice-calendars) — author the calendar, per-DID attach, precedence and troubleshooting
* [Inbound number routing](/guides/inbound-number-routing) — per-route `business_hours` and `holiday_calendar_id` fields
* [ACD queues](/guides/voice-queues) — the queue surface that inherits from this page
* [Workspace general settings](/guides/organization-general-settings) — the sibling org-level page: timezone, locale, plan, danger zone