How to list roles by role IDs in Zoho Desk

Listing roles by their IDs in Zoho Desk is straightforward using a single GET request to the roles endpoint, passing one or more role IDs directly in the URL path.

Why this matters

When building automations, auditing permissions, or syncing role data with external systems, you often need to retrieve specific role details without pulling every role in your organisation. Targeting roles by ID lets you fetch only what you need, reducing unnecessary API overhead. This is especially useful when you already have role IDs stored from a previous lookup and want to enrich or validate that data programmatically.

Step-by-step

Step 1. Ensure your Zoho Desk OAuth token includes the Desk.basic.READ scope. Role and agent data falls under the "basic" permission group, so without this scope the request will be rejected before it reaches the endpoint. ^[7]

Step 2. Construct your request URL using the pattern below, substituting {role_ids} with the actual ID or comma-separated list of IDs you want to retrieve:

GET /api/v1/roles/{role_ids}

For example, to look up a single role you might call /api/v1/roles/12345678, or supply multiple IDs if the endpoint accepts a comma-separated string in that path segment. ^[1]

Step 3. Optionally include the p parameter as a query-string dictionary to control pagination or filtering on the response. This is the same pattern used across other Zoho Desk list operations. ^[1]

Step 4. In Python, the call maps to the listrolesbyroleids method. A minimal invocation looks like this:

result = api.list_roles_by_role_ids(role_ids="12345678")

If you need to pass additional query parameters, supply them as a dictionary in the second argument:

result = api.list_roles_by_role_ids(role_ids="12345678,87654321", p={"limit": 10})

The method issues a GET request to /api/v1/roles/{role_ids} and returns the parsed response. ^[1]

Step 5. If your integration also needs to know which agents are assigned to a given role, there is a companion endpoint at /api/v1/roles/{role_id}/agents that accepts a single role ID and returns the associated agents. This is a separate call from the role-lookup itself. ^[5]

Step 6. Make sure your API client is initialised with a valid org_id. The Zoho Desk client requires the organisation ID to be set on the connection; if it is missing, the system will attempt to auto-discover it by calling the organisations endpoint on first use and persisting the result for subsequent requests. ^[6]

Common pitfalls

• Missing Desk.basic.READ scope — Role data is gated behind the basic read permission. If you only granted ticket or contact scopes during OAuth setup, role endpoints will return an authorisation error. Double-check your configured scopes include Desk.basic.READ. ^[7]
• Confusing the two role endpoints — /api/v1/roles/{roleids} retrieves role *details* by ID, while /api/v1/roles/{roleid}/agents retrieves the *agents* belonging to a role. Using the agents endpoint when you want role metadata (or vice versa) will return unexpected data. ^[1][5]
• Uninitialised orgid — Zoho Desk's API is organisation-scoped. If the orgid is blank at request time, the client will attempt a discovery call first, which adds latency and can fail if the OAuth token lacks organisation-read permissions. Pre-populate org_id wherever possible. ^[6]

What to check

• Confirm the response contains the expected role names and permission levels for each ID you supplied.
• Verify that Desk.basic.READ (and any other required scopes) appear in your active OAuth token before going to production. ^[7]
• If you plan to follow up with agent lookups, cross-reference the role IDs returned here against the /api/v1/roles/{role_id}/agents endpoint to ensure agent assignments are consistent with your expected configuration. ^[5]

---

*Beam Help provides independent expert guidance for Zoho products and is not official Zoho support. Always refer to Zoho's own documentation for the latest API changes.*