How to retrieve assignment rules in Zoho

Retrieving assignment rules in Zoho CRM is done via a single authenticated GET request to the /settings/assignment_rules endpoint, passing the target module as a parameter.

Why this matters

Assignment rules control how incoming records — leads, contacts, deals, and more — are automatically distributed to your sales team. If you're building an integration, auditing your CRM configuration, or syncing rules to an external system, you'll need to programmatically fetch these rules. This is also useful when troubleshooting why records aren't being routed as expected. As a reminder, Beam Help is independent expert support for Zoho and is not official Zoho support.

---

Step-by-step

Step 1. Register your application and obtain OAuth credentials by visiting the Zoho API Console, creating a Server-based Application, and noting your Client ID and Client Secret. Set your redirect URI (for example, http://localhost:8080/api/auth_callback) and ensure you include the scope ZohoCRM.settings.ALL among your selected scopes. ^[8]

Step 2. Generate an OAuth authorization URL by constructing a request with your clientid, redirecturi, scope, responsetype, and accesstype parameters. The access_type should be set to offline and prompt to consent so that a refresh token is issued alongside the access token. ^[2]

Step 3. Exchange the authorization code returned by Zoho for an access token and refresh token. Send a POST request to Zoho's token endpoint with granttype: authorizationcode, your clientid, clientsecret, redirecturi, and the code value. Store the resulting accesstoken, refreshtoken, apidomain, and tokenexpiresat values securely for later use. ^[2]

Step 4. When your access token expires, use the stored refresh token to obtain a new one. Send a POST request with granttype: refreshtoken along with your clientid and clientsecret. Update your stored accesstoken and tokenexpires_at values after each successful refresh so subsequent calls remain authenticated. ^[3]

Step 5. With a valid access token in hand, call the assignment rules endpoint. Issue a GET request to:

GET /settings/assignment_rules?module=<ModuleName>

The module parameter (referred to as m in the underlying implementation) specifies which Zoho CRM module's assignment rules you want to retrieve — for example, Leads, Contacts, or Deals. ^[1]

In Python, this call looks like:

def get_assignment_rules(self, m: str):
    return self.c.request("GET", "/settings/assignment_rules", {"module": m})

The client object (self.c) must already hold a valid, refreshed access token before making this call. ^[1]

Step 6. Handle the response. A successful call returns the assignment rules configured for the specified module. If the token has expired or the scope is insufficient, you will receive an authentication error — in that case, trigger the token refresh flow described in Step 4 and retry. ^[3]

---

Common pitfalls

• Missing scope. If ZohoCRM.settings.ALL is not included in your OAuth scope configuration, the API will reject the request. Double-check your registered scopes in the Zoho API Console and in your environment configuration. ^[8]

• Expired access token. Zoho access tokens have a limited lifetime (typically 3600 seconds). If tokenexpiresat has passed and you haven't refreshed, the call will fail. Always check expiry before making a request and refresh proactively. [^2, ^3]

• Wrong data centre. Zoho operates across multiple data centres (com, eu, in, com.au, jp). Your api_domain returned during token exchange should be used as the base URL for all API calls — don't hardcode https://www.zohoapis.com if your org is on a different DC. [^5, ^8]

• Module name case sensitivity. The module parameter must match Zoho CRM's internal module API name exactly. Use the API name (e.g., Leads, not leads) to avoid a "module not found" error. ^[1]

---

What to check

• Scope is present: Confirm that ZohoCRM.settings.ALL appears in your registered OAuth scopes and in your .env configuration before making the call. ^[8]
• Token is fresh: Verify that your stored tokenexpiresat is in the future; if not, run the refresh flow before calling the endpoint. ^[3]
• Correct base URL: Ensure you are using the api_domain value returned during token exchange as the root of your API requests, not a hardcoded domain. ^[5]