How to delete a role in Zoho Desk

Deleting a role in Zoho Desk is done via a single authenticated API call that targets the role by its unique identifier. Here's everything you need to make it work cleanly.

Why this matters

Role management is central to controlling what your Zoho Desk agents can see and do. Over time, organisations accumulate redundant or outdated roles that clutter the setup and confuse administrators. Knowing how to remove them programmatically — rather than hunting through the UI — saves time and keeps your configuration tidy, especially when managing roles at scale through automation or integrations.

> Note: Beam Help is independent expert support for Zoho — we are not official Zoho support.

---

Step-by-step

Step 1. Confirm you have the correct OAuth scopes.

Before making any API call, verify that your connected Zoho Desk OAuth token includes the necessary permissions. The scope required for settings-level operations (which includes role management) is Desk.settings.DELETE — alongside related scopes such as Desk.settings.READ and Desk.settings.ALL for broader access. ^[3]

Step 2. Retrieve the role_id you want to delete.

You cannot delete a role without knowing its exact identifier. Use a GET request against the roles endpoint (or check your Zoho Desk admin panel) to list existing roles and note the role_id of the one you want to remove. Store this value — you'll pass it directly into the delete call.

Step 3. Make the DELETE request.

Send a DELETE request to the following endpoint, substituting the actual role identifier for {role_id}: ^[1]

DELETE /api/v1/roles/{role_id}

The operation name is deleterole, and it accepts roleid as its primary path parameter, with an optional p parameter for any additional query options. ^[1]

Step 4. Use the Python client helper (if applicable).

If you are working with a Python-based integration, the call maps to a straightforward client method. Pass the role_id as a string, and optionally supply a dictionary for the p parameter: ^[1]

def delete_role(self, role_id: str, p: dict = None):
    return self.c.request("DELETE", f"/api/v1/roles/{role_id}", p, None)

Step 5. Initialise the Desk client with the correct org_id.

Zoho Desk API calls require your organisation ID to be set on the client. When building the ZohoDeskClient instance, pass the orgid alongside your API domain and access token. If the orgid is not yet stored, the client can auto-discover it by calling the organisations endpoint and persisting the first result. ^[6]

Step 6. Handle token refresh proactively.

Access tokens expire. Wrap your delete call inside a flow that checks token validity and refreshes using the stored refreshtoken before the request is sent. A tokenrefresher function should fetch the latest refresh token from your data store, call the OAuth refresh endpoint, and update the stored access_token and expiry timestamp. ^[6]

---

Common pitfalls

• Wrong product endpoint. Zoho CRM also has a role-deletion endpoint (DELETE /Contacts/roles/{roleid}), but that is for *deal contact roles* in CRM — not Desk agent roles. ^[2] Make sure you are targeting /api/v1/roles/{roleid} and using a Desk-authenticated client, not a CRM client. ^[1]

• Missing or expired orgid. Zoho Desk requires the organisation ID on every request. If orgid is blank or stale, the API will reject the call. Always verify it is populated before executing the delete. ^[6]

• Insufficient OAuth scope. If your token was generated without Desk.settings.DELETE (or the broader Desk.settings.ALL), the API will return an authorisation error. Re-generate your token with the full settings scope group included. ^[3]

• Deleting a role that still has agents assigned. The API may refuse to delete a role that has active agents attached to it. Reassign or remove those agents from the role before attempting deletion.

---

What to check

• Scope coverage: Confirm your active OAuth token includes Desk.settings.DELETE or Desk.settings.ALL before calling the endpoint. ^[3]
• Correct endpoint and client: Verify you are calling /api/v1/roles/{roleid} via a ZohoDeskClient instance — not a CRM client — and that orgid is populated. ^[1][6]
• Role no longer appears: After a successful DELETE, perform a GET on the roles list to confirm the role has been removed and no agents are unexpectedly left without a role assignment.