How to list associable teams in Zoho Desk

Listing associable teams in Zoho Desk is straightforward once you know which API endpoint to call and how to pass the right parameters. This article walks you through the process using the Zoho Desk REST API.

Why this matters

When building integrations or automations on top of Zoho Desk, you often need to know which teams can be associated with a given resource — for example, when routing tickets or assigning agents. The "associable teams" endpoint gives you a filtered list of teams eligible for association, which is distinct from simply listing all teams across every department. Understanding the difference helps you avoid assigning tickets to teams that aren't eligible, and keeps your workflows clean.

Step-by-step

Step 1. Confirm your OAuth scopes are configured correctly before making any API call. Your Zoho Desk integration needs at minimum Desk.basic.READ in its scope list to read team and agent data. Check your OAuth configuration and ensure this scope — along with any others your app requires — is present. ^[5]

Step 2. Make a GET request to the /api/v1/teams/associable endpoint. This is the dedicated operation for retrieving teams that can be associated, and it accepts an optional query-parameter dictionary (commonly referred to as p) for filtering or pagination. ^[1]

GET /api/v1/teams/associable

In Python, the call looks like this:

result = desk_client.list_associable_teams(p={"limit": 20})

The p argument is optional — omit it entirely if you want the default response with no additional filters applied. ^[1]

Step 3. If you need a broader picture — all teams across every department your account is associated with — use the separate GET /api/v1/teams endpoint instead. This operation, listteamsfromallassociated, returns teams from all linked departments rather than only those eligible for association. ^[3]

GET /api/v1/teams

result = desk_client.list_teams_from_all_associated(p=None)

Use this endpoint when you want a complete inventory of teams, and the associable endpoint when you need to restrict results to teams that are valid targets for an association action. ^[3]

Step 4. If your use case is agent-specific — for instance, you want to know which teams a particular agent already belongs to — there is a third endpoint scoped to an individual agent. Send a GET request to /api/v1/agents/{agentid}/teams, replacing {agentid} with the numeric or string identifier of the agent in question. ^[8]

GET /api/v1/agents/{agent_id}/teams

result = desk_client.list_associated_teams_of_agent(agent_id="98765", p=None)

This is useful for auditing team membership or pre-populating UI dropdowns filtered to a specific agent's context. ^[8]

Step 5. Parse the response. All three endpoints return their data through the same underlying request mechanism, so the response structure will follow the standard Zoho Desk API envelope. Iterate over the returned collection to extract team IDs, names, and any other attributes your integration needs. ^[1][3][8]

Common pitfalls

• Missing Desk.basic.READ scope. This is the most common reason these endpoints return a 401 or 403. Double-check that Desk.basic.READ (and Desk.basic.CREATE if you plan to write) is included in your OAuth scope string. A missing scope will silently block access to agent and team data even if ticket-related scopes are present. ^[5]

• Confusing "associable" with "all teams." The /api/v1/teams/associable endpoint is intentionally narrower than /api/v1/teams. If you call the wrong one, you may either see too few teams (and miss valid options) or too many (and allow invalid associations). Match the endpoint to your actual use case. ^[1][3]

• Forgetting the orgid. Zoho Desk is multi-org aware. If your connection has not yet resolved the correct deskorg_id, API calls may return data for the wrong organisation or fail entirely. Ensure the org ID is discovered and stored before making team-related requests. ^[4]

What to check

• Verify that Desk.basic.READ appears in your active OAuth scope configuration and that the token has been re-issued after any scope changes. ^[5]
• Confirm the response from /api/v1/teams/associable returns a non-empty list; if it is empty, cross-check that your account has teams configured in Zoho Desk and that the correct org_id is being used. ^[1][4]
• If you are filtering by agent, validate that the agentid you pass to /api/v1/agents/{agentid}/teams is a valid, active agent identifier in your Desk organisation. ^[8]

---

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