How to list team members in Zoho Desk

Listing team members in Zoho Desk is straightforward once you have a valid team ID and the correct OAuth scopes in place — a single API call returns the full member roster for any given team.

Why this matters

Support managers often need a quick programmatic view of who belongs to a specific team, whether for auditing assignments, building dashboards, or syncing agent data with external tools. Knowing the exact endpoint and required permissions saves time and prevents authentication errors before they reach production. This is especially relevant if you are integrating Zoho Desk into a custom workflow or AI assistant.

Step-by-step

Step 1. Confirm your OAuth connection is authenticated for Zoho Desk and that your token includes the Desk.basic.READ scope. This scope covers organisations, agents, and departments — the foundational data layer that team membership falls under. Without it, the API will reject the request before returning any data. ^[5]

Step 2. Identify the team_id for the team whose members you want to list. You can find this value in your Zoho Desk admin panel under the Teams section, or by first calling the teams list endpoint to retrieve all team IDs programmatically. Store this value — you will pass it as a path parameter in the next step. ^[4]

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

GET /api/v1/teams/{team_id}/members

The operation name for this call is listdetailsofteammembers. It accepts two parameters: team_id (required, the team's unique identifier) and p (optional, a dictionary for pagination or additional query parameters). ^[4]

In Python, using a Zoho Desk client wrapper, the call looks like this:

def list_details_of_team_members(self, team_id: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/teams/{team_id}/members", p, None)

^[4]

Step 4. Ensure your Desk API client is initialised with a valid orgid. If the organisation ID has not been stored yet, the client can auto-discover it by first calling the organisations endpoint and persisting the first result. Without a resolved orgid, requests to team endpoints may fail or return unexpected results. [^3, ^7]

Step 5. Parse the response. The API returns member detail objects for each agent belonging to the team. Display key fields such as name, email, and status to the end user, skipping internal IDs and empty values for readability. ^[2]

Common pitfalls

• Missing Desk.basic.READ scope. This is the most common cause of 403 errors when querying agents, departments, or teams. Double-check that this scope is included in your OAuth configuration alongside any ticket or contact scopes. ^[5]

• No orgid set on the client. Zoho Desk's API routes requests through an organisation context. If orgid is blank, the client may silently fail or hit the wrong tenant. Always verify the value is populated before making team-related calls — auto-discovery on first connection is a reliable fallback. [^3, ^7]

• Incorrect data centre. The base URL for Zoho Desk varies by region (e.g., desk.zoho.com for the US, desk.zoho.eu for Europe). Requests sent to the wrong data centre will fail authentication. Confirm the dc value matches the region where your Zoho account is hosted. ^[6]

• Pagination not handled. The p parameter supports pagination. If a team has many members, the first response may be truncated. Pass appropriate page parameters to retrieve the full list. ^[4]

What to check

• Verify that Desk.basic.READ appears in your active OAuth scopes before making the call. ^[5]
• Confirm the team_id value is correct and corresponds to an existing team in your Zoho Desk organisation. ^[4]
• Check that org_id is resolved and stored on your API client instance so all subsequent requests are routed to the right organisation. [^3, ^7]

---

*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.*