How to list teams for a role in Zoho Desk

Listing the teams associated with a specific role in Zoho Desk is straightforward via the Desk REST API — a single GET request returns all linked teams for the role you specify.

Why this matters

When managing agent permissions and workflows in Zoho Desk, roles and teams are closely related: a role defines what an agent can do, while teams group agents for routing and collaboration. Knowing which teams are tied to a given role helps administrators audit access, troubleshoot ticket routing, and keep org structures clean. You'll need this lookup whenever you're onboarding new agents or restructuring your support hierarchy.

Step-by-step

Step 1. Confirm your OAuth token includes the correct Zoho Desk scopes before making any API call. At minimum you'll need Desk.basic.READ in your authorised scope set, which covers organisations, agents, and departments — the category that roles and teams fall under. ^[3]

Step 2. Identify the role_id for the role you want to inspect. You can retrieve this from your Zoho Desk admin panel under Setup → Agent Roles, or by calling the roles list endpoint first. Keep this ID handy — it forms part of the request path.

Step 3. Make a GET request to the following endpoint, substituting your actual role identifier:

GET /api/v1/roles/{role_id}/teams

This operation — internally referred to as listassociatedteamsfora — returns the teams that have been associated with the specified role. ^[2]

Step 4. If you need to paginate through a large result set, pass the optional p query parameter to move through pages of results. The endpoint signature accepts both role_id (path parameter) and p (optional pagination parameter). ^[2]

Step 5. A minimal Python call using the Desk client wrapper looks like this:

response = desk_client.list_associated_teams_for_a(
    role_id="your_role_id_here",
    p={"page": 1}   # optional pagination
)

The client issues a GET to /api/v1/roles/{role_id}/teams and returns the parsed response body. ^[2]

Step 6. Parse the response payload. The returned object will contain the team records linked to that role. Iterate over the list to extract team names, IDs, or any other attributes your workflow requires.

Common pitfalls

• Missing scope: If your OAuth token was generated without Desk.basic.READ, the API will reject the request with an authorisation error. Double-check your configured scopes and regenerate the token if needed. ^[3]
• Wrong org context: Zoho Desk is multi-org aware. If your integration manages more than one organisation, ensure the org_id on your API client is set to the correct Desk organisation before calling the endpoint — otherwise you may query roles that belong to a different portal entirely. ^[4]
• Pagination oversight: If a role is linked to many teams, the first page may not return all of them. Always check whether the response indicates additional pages and use the p parameter to retrieve the full set. ^[2]

What to check

• Scope coverage: Verify that Desk.basic.READ (and any other required scopes) are present in your active OAuth token before running the request. ^[3]
• Correct role_id: Confirm the role ID you're passing actually exists in the target Zoho Desk organisation — a mismatched ID will return an empty or error response. ^[2]
• Org ID alignment: After the call, validate that the teams returned belong to the expected portal/organisation, especially in multi-org setups. ^[4]

---

*Beam Help provides independent expert support for Zoho products and is not official Zoho support. For platform-level issues, always cross-reference the Zoho Desk API documentation directly.*