How to retrieve automation settings in Zoho

Retrieving automation settings in Zoho CRM is done via a single authenticated GET request to the /settings/automation endpoint, optionally filtered by module. Here is everything our team at Beam Help — independent expert support for Zoho, not official Zoho support — has documented about making that call reliably.

Why this matters

When you need to audit, replicate, or troubleshoot workflow rules and automation logic inside Zoho CRM, you need a programmatic way to pull the current configuration. The /settings/automation endpoint gives you exactly that, returning the automation settings for your org — or for a specific module if you narrow the query. This is especially useful when building admin tooling, running compliance checks, or migrating settings between environments.

Step-by-step

Step 1. Ensure a valid OAuth connection exists.

Before any API call can succeed, your integration must hold a live access token for the target user. The connection record is looked up from your local store by user_id, and if the token is within 120 seconds of expiry it is refreshed automatically before the request goes out — this proactive refresh window is designed to prevent mid-request 401 errors. ^[5]

Step 2. Obtain a Zoho CRM API client instance.

Call getzohoapi(userid, apptype="crm") to receive a fully initialised API object. Internally this function retrieves the stored connection, wires up a tokenrefresher callback that re-fetches a fresh accesstoken from Zoho's token endpoint when needed, and returns a ZohoCrmApi instance ready to make calls. ^[1]

The tokenrefresher works by reading the latest refreshtoken from the database, posting it to Zoho's token URL with your clientid and clientsecret, and persisting the new accesstoken and tokenexpiresat back to the zohoconnections table. ^{[1] [2]}

Step 3. Call the automation settings endpoint.

With your API object in hand, invoke the get_automation method:

result = api.get_automation()          # all modules
result = api.get_automation(m="Leads") # scoped to a specific module

Under the hood this issues a GET request to /settings/automation, appending {"module": m} as a query parameter only when a module name is supplied. ^[3]

The operation identifier is get_automation and the HTTP method is GET /settings/automation. ^[3]

Step 4. Handle the response.

The method returns whatever the Zoho CRM REST API sends back — typically a JSON object containing your automation rules. Check the top-level keys for error indicators before processing. If the token had silently expired, the token_refresher callback fires automatically and the client retries, so transient auth failures are handled without extra code on your side. ^{[1] [5]}

Step 5. (Optional) Scope by module.

Pass the CRM module name as the m argument — for example "Leads", "Contacts", or "Deals" — to limit the response to automation rules belonging to that module only. Omitting the argument returns settings across all modules. ^[3]

Common pitfalls

• Missing or expired connection record. If getzohoconnection returns None because no row exists in zohoconnections for the given userid, getzohoapi will also return None and any subsequent API call will fail with an attribute error. Always verify the OAuth flow completed successfully and a connection row was persisted before attempting settings retrieval. ^{[1] [5]}

• Wrong apptype. The automation settings endpoint lives in Zoho CRM, so apptype must be "crm". Passing "desk" routes the client to ZohoDeskApi instead, which targets a completely different set of endpoints and will not expose CRM automation settings. ^[1]

• Token refresh loop on bad refreshtoken. If ZohoOAuth.refreshtokens returns a payload without an access_token key — for example when the refresh token has been revoked — the refresher returns None and the call will fail. The fix is to re-run the OAuth authorisation flow to obtain a fresh token pair. ^{[2] [5]}

• Port mismatch during initial OAuth. The OAuth redirect URI is registered for http://localhost:8080/api/authcallback. Running the server on any other port will cause the authorisation callback to fail, meaning no tokens are ever stored and every downstream API call — including getautomation — will have nothing to work with. ^[4]

What to check

• Confirm a valid token is stored — query zohoconnections for the target userid and verify tokenexpiresat is in the future, or that the refresh path is functional.
• Verify the endpoint response structure — ensure the returned JSON contains the expected automation rule keys and is not an error object (e.g. {"code": "INVALID_TOKEN", ...}).
• Confirm module name spelling — if you passed the m parameter, cross-check the module API name (case-sensitive) against your Zoho CRM module list to avoid an empty or erroneous response. ^[3]