How to retrieve data sharing rules in Zoho

Retrieving data sharing rules in Zoho CRM and Zoho Desk is straightforward via dedicated API endpoints — you can pull either a full list of rules or a single rule by its ID, depending on your use case.

Why this matters

Data sharing rules control which records are visible across roles and territories in your Zoho organisation. Auditing or programmatically inspecting these rules is essential when onboarding new users, troubleshooting visibility gaps, or automating governance checks. As independent expert support (Beam Help — not official Zoho support), we walk through both the CRM and Desk approaches below.

Step-by-step

Step 1. Authenticate and obtain an access token.

Before calling any settings endpoint, your integration must hold a valid OAuth access token. The token is retrieved via Zoho's OAuth flow and expires after the period specified in the expiresin field of the token response (typically 3600 seconds). Store the accesstoken value and refresh it before it lapses. ^[4]

Step 2. Retrieve all data sharing rules in Zoho CRM.

Send a GET request to the /settings/datasharingrules endpoint. This returns the complete collection of data sharing rules configured for your CRM organisation. No additional path parameters are required. ^[2]

# Example call
response = client.get_data_sharing_rules()

Pass your Authorization: Bearer <access_token> header with every request. ^[4]

Step 3. Retrieve a single data sharing rule by ID in Zoho CRM.

When you only need details for one specific rule, append the rule's identifier to the path: /settings/datasharingrules/{ruleid}. Replace {ruleid} with the actual ID string of the rule you want to inspect. ^[1]

# Example call
response = client.get_data_sharing_rule(rule_id="your_rule_id_here")

This targeted call is more efficient than fetching the full list when you already know the rule identifier. ^[1]

Step 4. Retrieve data sharing rules management documentation in Zoho Desk.

For Zoho Desk environments, the relevant endpoint is GET /api/v1/doc/datasharingrulesmanagemen. This endpoint accepts an optional p parameter for pagination or filtering purposes. ^[3]

# Example call
response = client.get_data_sharing_rules_management(p={"page": 1})

Ensure your Desk OAuth token carries the appropriate Desk.settings.READ scope before making this call. ^[7]

Step 5. Confirm your OAuth scopes cover settings access.

For Zoho CRM, your token must include ZohoCRM.org.ALL or an equivalent org-level scope to read settings resources. For Zoho Desk, the required scope is Desk.settings.READ (or Desk.settings.ALL). Without these scopes, the API will return an authorisation error rather than rule data. ^[7]

Common pitfalls

• Missing or expired token. If the accesstoken key is absent from the OAuth response, the integration will surface an error rather than proceeding. Always validate that accesstoken exists in the token payload before making downstream calls. ^[4]

• Wrong endpoint for the product. The CRM rules endpoint (/settings/datasharingrules) and the Desk rules endpoint (/api/v1/doc/datasharingrulesmanagemen) are distinct. Sending a CRM-scoped token to the Desk endpoint — or vice versa — will result in an authentication or not-found error. ^[1][2][3]

• Incorrect ruleid format. The single-rule endpoint requires a valid ruleid string in the path. Passing a null, empty, or incorrectly formatted identifier will cause the request to fail or return an unexpected result. ^[1]

• Insufficient Desk scopes. Zoho Desk has granular scope definitions. If your token was generated without Desk.settings.READ, the data sharing rules management endpoint will be inaccessible even if other Desk scopes are present. ^[7]

What to check

• Scope coverage: Verify your OAuth token includes ZohoCRM.org.ALL for CRM calls and Desk.settings.READ for Desk calls before executing any request. ^[7]
• Token validity: Confirm the tokenexpiresat timestamp has not passed; refresh the token proactively if it is within a few minutes of expiry. ^[4]
• Correct base URL and product: Double-check that CRM requests target the /settings/datasharingrules path and Desk requests target /api/v1/doc/datasharingrulesmanagemen, as mixing them will produce errors. ^[1][2][3]