How to delete a team in Zoho Desk

Deleting a team in Zoho Desk via the API requires a single authenticated DELETE request targeting the specific team's unique identifier. Here's everything you need to know to do it cleanly and safely.

Why this matters

Teams in Zoho Desk help route tickets and organise agents — but over time, redundant or restructured teams can clutter your setup. Whether you're automating a cleanup script or building an admin workflow, knowing how to programmatically remove a team is essential for keeping your Zoho Desk configuration tidy. This guide covers the API approach, which is the most reliable method for bulk or automated deletions.

> Note: Beam Help is an independent expert support resource — not official Zoho support.

---

Step-by-step

Step 1. Confirm your OAuth scopes are in place.

Before making any destructive API call, verify that your connected OAuth client includes the necessary Zoho Desk permissions. Settings-level operations — including team management — require scopes such as Desk.settings.ALL or at minimum Desk.settings.DELETE to be present in your token configuration. ^[2]

Step 2. Retrieve the team_id you want to delete.

You'll need the unique identifier for the team before issuing the delete request. If you don't already have it stored, use a GET request against the teams endpoint to list all teams and note the team_id of the one you want to remove. Keep this value handy for the next step.

Step 3. Issue the DELETE request to the teams endpoint.

Send an authenticated HTTP DELETE to the following endpoint, substituting your actual team identifier in place of {team_id}: ^[1]

DELETE /api/v1/teams/{team_id}

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

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

Pass the team_id as a string argument. The optional p parameter can carry any additional query parameters if required. ^[1]

Step 4. Handle the API response.

A successful deletion will return an appropriate HTTP success status. If the response indicates an error — such as a 404 (team not found) or a 403 (insufficient permissions) — revisit Steps 1 and 2 to confirm the scope configuration and the correctness of the team_id you supplied. [^1, ^2]

---

Common pitfalls

• Wrong endpoint for groups vs. teams. Zoho Desk has a separate endpoint for deleting Help Center groups (DELETE /api/v1/helpcenter/{helpcenterid}/groups/{groupid}), which is a completely different resource from a team. Make sure you're targeting /api/v1/teams/{team_id} and not a groups or departments endpoint. ^[4]

• Missing or insufficient OAuth scopes. If your token was generated without Desk.settings.DELETE or Desk.settings.ALL, the API will reject the request. Double-check the scopes list in your OAuth configuration before debugging elsewhere. ^[2]

• Confusing teams with departments. Departments have their own set of endpoints (e.g., for dissociating agents or removing logos). A team deletion will not affect department membership or configuration — these are managed separately. [^3, ^5]

---

What to check

• Scope coverage: Confirm your active OAuth token includes at least one of Desk.settings.ALL or Desk.settings.DELETE before making the call. ^[2]
• Correct resource ID: Verify the team_id you're passing actually corresponds to a team (not a department or Help Center group) by cross-referencing with a GET teams list first. ^[1]
• Response status: After the DELETE call completes, confirm the HTTP response indicates success — any error code should be investigated against your credentials and the validity of the team ID. ^[1]