How to retrieve appointment preferences in Zoho

Retrieving appointment preferences in Zoho CRM is straightforward via a single settings API endpoint that returns your organisation's scheduling configuration in one call.

Why this matters

When building integrations or automations around Zoho CRM's scheduling features, you often need to read the current appointment preferences programmatically — for example, to validate booking rules, sync availability windows, or audit configuration changes. Knowing the exact endpoint and how to wire it into an authenticated client saves significant trial-and-error time. As always, Beam Help is independent expert support for Zoho and is not official Zoho support.

Step-by-step

Step 1. Ensure your Zoho CRM OAuth connection is active and your access token is valid. The API layer handles token refresh automatically by looking up the stored refreshtoken, calling the OAuth refresh endpoint, and persisting the new accesstoken back to your database before making any downstream request. ^[3]

Step 2. Confirm that your OAuth scopes include the necessary CRM settings permissions. Your scope configuration should cover ZohoCRM.settings or the broader ZohoCRM.org.ALL scope so the settings endpoint is accessible. Without the right scopes, the request will be rejected before it reaches the server. ^[2]

Step 3. Instantiate your Zoho CRM API client using the authenticated connection for the target user. Pass app_type="crm" when calling your API factory function so the correct client class is initialised rather than the Desk variant. ^[3]

Step 4. Call the appointment preferences endpoint. Issue an HTTP GET request to /settings/appointment_preferences using API version 6. In Python, this looks like: ^[1]

def get_appointment_preferences(self):
    return self.c.request("GET", "/settings/appointment_preferences", version=6)

The method delegates to your underlying HTTP client (self.c), which attaches the bearer token and routes to the correct data centre domain automatically. ^[1]

Step 5. Parse the response. The endpoint returns a JSON payload containing your organisation's appointment preference settings. Inspect the returned dictionary for the fields relevant to your use case — availability rules, booking windows, or notification settings — and handle any error keys before proceeding. ^[1]

Related settings endpoints

If you need to retrieve other preference categories alongside appointment data, two sibling endpoints follow the same pattern and version:

• Call preferences — GET /settings/telephony (operation: getcallpreferences) ^[4]
• Service preferences — GET /settings/servicepreferences (operation: getservice_preferences) ^[5]

All three use API version 6 and the same authenticated client, so you can batch them in a single session without re-authenticating.

Common pitfalls

• Stale access tokens. If the token has expired and the refresh logic fails (for example, because the refreshtoken row is missing from your database), getzoho_api returns None and the settings call will never fire. Always check that the returned API object is not None before invoking any method on it. ^[3]
• Wrong apptype. Passing apptype="desk" will initialise a ZohoDeskClient instead of the CRM client, and the /settings/appointment_preferences path will not exist on that client — resulting in a confusing 404 or attribute error. ^[3]
• Insufficient scopes. If your OAuth application was authorised with a minimal scope set that excludes CRM organisation or settings scopes, the API will return an authorisation error. Re-authorise the connection with the full ZohoCRM.org.ALL scope included. ^[2]

What to check

• Token validity — confirm the stored accesstoken is not expired and that the tokenrefresher function can successfully obtain a new one from your zoho_connections table. ^[3]
• Scope coverage — verify that ZohoCRM.org.ALL or an equivalent settings scope is present in the authorised scope list for your OAuth client. ^[2]
• API version — ensure the request explicitly specifies version 6, as the /settings/appointment_preferences endpoint is defined against that version and may not resolve correctly on earlier versions. ^[1]