How to delete a profile in Zoho Desk

Deleting a profile in Zoho Desk via the API is a straightforward single-call operation — you issue a DELETE request against the profiles endpoint with the target profile's ID. As independent expert support (not official Zoho support), Beam Help walks you through exactly what's needed.

Why this matters

Profiles in Zoho Desk control what agents can see and do within your help desk. Over time, organisations accumulate redundant or outdated profiles that need to be cleaned up. Removing stale profiles keeps your permission structure tidy and reduces the risk of agents operating under incorrect access rules.

Step-by-step

Step 1. Ensure your OAuth token carries the correct Zoho Desk scopes before making any API call. The scopes you'll need include Desk.settings.ALL or at minimum Desk.settings.DELETE, which govern settings-level operations such as profile management. ^[2]

Step 2. Identify the profile_id of the profile you want to remove. You can retrieve this by listing existing profiles through the Zoho Desk API and noting the ID returned in the response. Store this value — you'll pass it directly into the delete request. ^[1]

Step 3. Construct and send the delete request. The operation targets the following endpoint:

DELETE /api/v1/profiles/{profile_id}

Replace {profile_id} with the actual ID you collected in Step 2. ^[1]

Step 4. If you're using a Python client, the call looks like this:

def delete_profile(self, profile_id: str, p: dict = None):
    return self.c.request("DELETE", f"/api/v1/profiles/{profile_id}", p, None)

Pass the profile ID as a string; the optional p parameter can carry any additional query parameters if required. ^[1]

Step 5. Make sure your API client is initialised with a valid Zoho Desk organisation ID (orgid). The client needs this to route requests correctly to your Desk instance. If the orgid is missing, the system can auto-discover it by calling the organisations endpoint first and persisting the returned ID. ^[6]

Common pitfalls

• Missing or incorrect scopes. If your OAuth token does not include Desk.settings.DELETE (or the broader Desk.settings.ALL), the API will reject the request with an authorisation error. Double-check the scopes configured in your environment. ^[2]

• Wrong profile ID. Passing an ID that doesn't exist or belongs to a different portal will result in a failed request. Always verify the profile_id by fetching the profile list before attempting deletion. ^[1]

• Destructive operation gating. In automated or AI-assisted workflows, delete operations are classified as "destructive" and may be blocked unless the system is explicitly configured to allow destructive actions. Confirm that your integration or tooling permits destructive-level permissions before triggering this call. ^[4]

• Missing org ID. Requests made without a valid org_id on the Desk client will fail to reach the correct organisation. Ensure the org ID is resolved and attached to the client before issuing the delete. ^[6]

What to check

• Confirm the OAuth token in use includes Desk.settings.DELETE or Desk.settings.ALL in its scope list. ^[2]
• Verify the profile_id you're targeting is valid by retrieving the current profile list beforehand. ^[1]
• After the delete call returns, attempt to fetch the same profile ID to confirm it no longer exists in Zoho Desk. ^[1]