Retrieving shift hours in Zoho CRM is straightforward once your OAuth connection is established — a single API call to the settings endpoint returns all shift-hour configuration for your organisation.
Why this matters
Business hours and shift calendars drive SLA calculations, automation triggers, and support availability windows inside Zoho CRM. If you are building an integration or auditing your CRM configuration programmatically, you need a reliable way to pull this data without navigating the UI manually. Understanding the underlying API call also helps when troubleshooting mismatches between expected and actual business-hours behaviour.
Step-by-step
Step 1. Ensure a valid OAuth connection exists for the user.
Before any API call can succeed, your application must hold a live access token for the target Zoho account. The connection record is looked up by user_id from your local store, and if the token is within 120 seconds of expiry it is automatically refreshed before the request is dispatched — this early-refresh buffer reduces mid-request 401 errors. [1]
Step 2. Instantiate the Zoho CRM API client.
Use the getzohoapi helper, passing the relevant userid and specifying "crm" as the apptype. This function retrieves the stored connection, wires up a token_refresher callback for seamless re-authentication, and returns a ready-to-use ZohoCrmApi instance alongside the connection record. [4]
Step 3. Call the getshifthours tool.
With the API client in hand, invoke getshifthours. Under the hood this issues an HTTP GET request to the /settings/shift_hours endpoint using API version 6. [2]
result = api.get_shift_hours()The method is also exposed as a named tool (getshifthours) within the CRM tool registry, so it can be triggered through the standard execute_tool dispatch path as well. [5]
Step 4. Handle the response.
The call returns the shift-hours configuration object from Zoho CRM. Parse the returned dictionary for the schedule details you need. If the response contains an "error" key, check token validity first — the OAuth layer returns {"error": "No access token in response"} when token exchange or refresh fails. [3]
Step 5. Refresh tokens proactively if running in a test or batch context.
When executing multiple sequential API calls (for example, during integration tests), re-check the tokenexpiresat value before each call and invoke the token_refresher if the current time is within the 120-second skew window. This pattern prevents a valid session from expiring mid-batch. [6]
---
Common pitfalls
- Stale or missing connection record. If
getzohoconnectionreturnsNone, no API call can be made. Verify thezohoconnectionstable contains a row for the targetuseridbefore proceeding. [1]
- Wrong
apptypepassed togetzohoapi. Passing"desk"instead of"crm"will route the request through the Zoho Desk client, which does not expose the/settings/shifthoursendpoint. Always use"crm"for this operation. [4]
- API version mismatch. The
getshifthoursimplementation explicitly targets version 6 of the Zoho CRM API. Overriding the version in a custom client wrapper may result in a 404 or an unexpected response schema. [2]
- OAuth scope gaps. The access token must have been granted the appropriate CRM settings scope during the initial authorisation flow. If the token was issued without settings-read permissions, the endpoint will return an authorisation error even though the token itself is valid. [7]
---
What to check
- Token freshness: Confirm
tokenexpiresatin your connection record is in the future (accounting for the 120-second skew) before making the call. [1] - Correct endpoint and version: Verify your client is targeting
GET /settings/shift_hoursat API version 6. [2] - Response structure: Ensure the returned object does not contain an
"error"key; if it does, re-examine your OAuth scopes and refresh-token validity. [3]
---
*Beam Help is an independent expert support resource for Zoho users — we are not official Zoho support. For platform-level issues, always cross-reference with Zoho's own documentation.*