Retrieving business hours in Zoho CRM is straightforward once your OAuth connection is established — a single GET request to the settings endpoint returns all configured business-hour data for your organisation.
Why this matters
Business hours drive a range of time-sensitive CRM behaviours, including SLA calculations, workflow scheduling, and support availability windows. If you are building an integration or auditing your Zoho CRM configuration programmatically, you need a reliable way to pull this data without navigating the UI each time. Understanding the underlying API call also helps when automating environment comparisons between sandbox and production orgs.
Step-by-step
Step 1. Ensure you have a valid, authenticated Zoho CRM connection for the user in question. The system checks whether a stored connection exists and automatically refreshes the access token if it is within 120 seconds of expiry, so you do not need to handle token rotation manually before making the call. [1]
Step 2. Obtain a ZohoCrmApi instance tied to the authenticated user. Internally this wraps a ZohoCrmClient that holds the apidomain and the current accesstoken, along with a token_refresher callback that can silently renew credentials mid-session if a 401 is encountered. [3]
Step 3. Call the business hours retrieval method on the API instance. The operation is mapped to:
GET /settings/business_hoursIn Python, this is invoked as:
def get_business_hours(self):
return self.c.request("GET", "/settings/business_hours", version=6)The request targets version 6 of the Zoho CRM API, so make sure your client is not hard-coded to an older version number. [4]
Step 4. Parse the response. A successful call returns a JSON payload containing your organisation's business-hour configuration. If the response contains an error key rather than the expected data structure, check the token validity and org permissions before retrying. [4]
Step 5. If you are running this inside an automated test harness, you can invoke the operation through the tool-call mechanism by posting to /api/chat with a JSON body that specifies "tool": "getbusinesshours" and an empty params object. The server extracts the tool result from data.tool_result in the response. [5]
---
Common pitfalls
- Stale or missing connection record. If
getzohoconnectionreturnsNonefor the givenuser_id, the API instance cannot be created and the call will fail silently. Always verify the connection row exists in your database before proceeding. [1]
- Wrong API version. The business hours endpoint is explicitly called with
version=6. Omitting the version parameter or defaulting to an earlier version may return a 404 or an unexpected response shape. [4]
- Missing org ID for multi-product setups. If your integration also uses Zoho Desk alongside CRM, be aware that Desk calls require a separate
orgidfield (deskorg_id) that is distinct from the CRM org identifier. Mixing these up will cause authentication failures on the wrong product. [3]
- Token expiry mid-request. Although the connection layer refreshes tokens proactively 120 seconds before expiry, long-running batch jobs can still hit a 401. The
token_refreshercallback is designed to handle this, but confirm it is wired up correctly in yourZohoCrmClientinstantiation. [^1, ^3]
---
What to check
- Confirm the access token is valid by verifying
tokenexpiresatis in the future before making the call, or by checking that the auto-refresh logic ran without error. [1] - Verify the correct API domain (
api_domain) is stored in the connection record — this value is returned during the initial OAuth token exchange and must match the data centre your org is hosted on. [6] - Inspect the raw response for an
errorkey; if present, cross-reference the error description against your OAuth scopes to ensure the CRM settings scope is included inConfig.ZOHO_SCOPES. [^2, ^6]
---
*Beam Help provides independent expert guidance for Zoho products and is not official Zoho support. Always test API calls against a sandbox org before running them in production.*