How to list agents in a department in Zoho Desk

Listing agents within a specific department in Zoho Desk is straightforward via the REST API — a single GET request to the departments endpoint returns the full agent roster for that department.

Why this matters

When building integrations, automations, or reporting dashboards on top of Zoho Desk, you often need to know exactly which agents belong to a given department before routing tickets, calculating workloads, or auditing team membership. Pulling this list programmatically saves you from manually cross-referencing the admin UI and keeps your integration in sync as team membership changes.

Step-by-step

Step 1. Identify the department_id for the department you want to query. You can find this value in your Zoho Desk admin panel under department settings, or by calling the departments list endpoint first to retrieve all department IDs in your account. ^[2]

Step 2. Construct your API request using the following endpoint pattern:

GET /api/v1/departments/{department_id}/agents

Replace {department_id} with the actual numeric or string ID of the target department. ^[2]

Step 3. Optionally, include the p query parameter to handle pagination if the department has a large number of agents. Pass it as a dictionary (or query string key-value pair) alongside your request. ^[2]

Step 4. Authenticate your request using your Zoho Desk OAuth token or API key in the request headers, as required by the Zoho Desk API authentication model. Ensure the token has sufficient scope to read department and agent data. ^[2]

Step 5. If you are using Python, the call can be structured as shown below — note that p is an optional parameter for pagination:

def list_agents_in_department(self, department_id: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/departments/{department_id}/agents", p, None)

This method issues a GET request to the agents sub-resource of the specified department. ^[2]

Step 6. Parse the JSON response. The returned payload will contain the agent records associated with that department, which you can then iterate over for your downstream use case — such as ticket assignment logic or reporting. ^[2]

Common pitfalls

• Wrong department ID format: Passing an incorrect or misformatted department_id will result in a failed request or an empty response. Always validate the ID against a fresh departments list before querying agents. ^[2]
• Missing pagination handling: If a department has many agents and you omit the p parameter, you may only receive the first page of results. Make sure your integration loops through all pages until the response indicates no further records. ^[2]
• Insufficient OAuth scope: Even if your token is valid, it must carry the correct read permissions for department and agent resources. A token scoped only to ticket operations will not return agent data. ^[2]

What to check

• Confirm that the department_id you are using matches an active department in your Zoho Desk account and has not been archived or deleted.
• Verify that the API response includes all expected agents — cross-reference the count against what you see in the Zoho Desk admin UI under that department's agent list.
• Ensure your pagination logic is correctly advancing the p parameter so no agents are silently omitted from large departments. ^[2]

---

*Beam Help is an independent expert support resource for Zoho products and is not official Zoho support. For billing or account-level issues, please contact Zoho directly.*