Skip to main content
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: 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 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 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). An id from anywhere else answers 422.
cURL
Read back the resolved defaults:
cURL
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 }.
Keep the timezone in the org default aligned with your Settings → General workspace timezone (general settings). The schedule timezone is explicit per schedule, so a mismatch resolves — it is just confusing to read later.

​
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. 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:
cURL
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