How to delete a layout rule in Zoho Desk

Deleting a layout rule in Zoho Desk is a straightforward API operation that requires the unique identifier of the rule you want to remove. Here at Beam Help — your independent expert support for Zoho, not official Zoho support — we'll walk you through exactly how to do it.

Why this matters

Layout rules in Zoho Desk control how fields and sections behave dynamically based on conditions, so outdated or conflicting rules can cause confusing agent experiences. Removing stale layout rules keeps your ticket forms clean and predictable. You may also need to delete a rule programmatically as part of a larger automation or migration script.

Step-by-step

Step 1. Gather your ruleId. Before making any API call, you need the unique identifier of the layout rule you want to delete. This is typically retrieved from a prior "list layout rules" API call or from your Zoho Desk admin settings. Store this value — you'll pass it directly into the endpoint path.

Step 2. Authenticate your request. Ensure your OAuth token includes the appropriate Zoho Desk scopes. For settings-level operations like deleting layout rules, your token should cover Desk.settings.ALL or at minimum Desk.settings.DELETE. ^[8]

Step 3. Send a DELETE request to the layout rules endpoint. The operation targets /api/v1/layoutRules/{ruleId}, where {ruleId} is replaced with the actual identifier from Step 1. ^[1]

Using the Python client, the call looks like this:

response = client.delete_layout_rule(ruleId="your_rule_id_here")

The method issues a DELETE HTTP request to /api/v1/layoutRules/{ruleId} and returns the server response. ^[1]

Step 4. Check the response. A successful deletion will return a 200 OK or 204 No Content status. If you receive an error, verify that the ruleId is correct and that your OAuth token has not expired.

---

Distinguishing layout rules from related operations

It is easy to confuse a layout rule deletion with other similar operations in Zoho Desk. Here is a quick reference so you target the right endpoint:

| What you want to delete | Endpoint |

|---|---|

| A layout rule | DELETE /api/v1/layoutRules/{ruleId} ^[1] |

| An entire layout | DELETE /api/v1/layouts/{layoutId} ^[4] |

| A validation rule on a layout | DELETE /api/v1/layouts/{layoutId}/validationRules/{validationRuleId} ^[3] |

| A section within a layout | DELETE /api/v1/layouts/{layoutId}/sections/{sectionId} ^[7] |

Make sure you are calling the layoutRules path and not the layouts path, as deleting a layout removes the entire form structure rather than just a conditional rule. ^[1][4]

Common pitfalls

• Wrong endpoint path. The layout rule endpoint is /api/v1/layoutRules/{ruleId} — note the plural layoutRules segment. Confusing this with /api/v1/layouts/{layoutId} will delete the entire layout instead of just the rule. ^[1][4]
• Insufficient OAuth scopes. If your token was generated without Desk.settings.DELETE or Desk.settings.ALL, the API will reject the request with an authorisation error. Double-check your scope configuration before troubleshooting elsewhere. ^[8]
• Stale or invalid ruleId. Passing an ID that no longer exists or belongs to a different organisation will result in a 404 Not Found response. Always confirm the ID against a fresh list call.

What to check

• Confirm the rule is gone by retrieving the list of layout rules after deletion and verifying the targeted ruleId no longer appears.
• Verify no dependent rules remain — if other layout rules referenced the deleted rule's conditions, those may behave unexpectedly and should be reviewed.
• Audit your OAuth scopes to ensure Desk.settings.ALL or Desk.settings.DELETE is present in your token, preventing silent permission failures on future calls. ^[8]