How to delete layouts in Zoho Desk

Deleting a layout in Zoho Desk is a permanent, high-risk action performed via the Zoho Desk API — there is no undo once the request is sent. Here at Beam Help (independent expert support for Zoho, not official Zoho support), we walk you through exactly what's involved.

Why this matters

Layouts in Zoho Desk control how ticket, contact, and other record forms are presented to agents. Over time, you may accumulate redundant or outdated layouts that clutter your settings. Removing them via the API keeps your configuration clean and ensures agents only see relevant form structures. You may also need to remove individual sections or layout rules as part of a broader restructure.

Step-by-step

Step 1. Confirm your OAuth scopes are in place.

Before making any delete call, verify that your connected OAuth client includes the necessary Desk settings permissions. The scopes you need are Desk.settings.ALL or at minimum Desk.settings.DELETE — these govern write access to Zoho Desk configuration resources. ^[3]

Step 2. Identify the layoutId you want to remove.

You cannot delete a layout without its unique identifier. Use a GET request against the layouts endpoint to list all available layouts and note the layoutId of the one you intend to remove. Keep this value handy — you will pass it as a path parameter in the next step.

Step 3. Send the DELETE request for the layout.

Issue a DELETE call to the following endpoint, substituting your target identifier into the path:

DELETE /api/v1/layouts/{layoutId}

An optional parameter object p can be passed alongside the request if your integration requires additional query parameters. ^[2]

In Python, the call looks like this:

client.delete_layout(layoutId="your-layout-id-here")

The function sends the DELETE method to /api/v1/layouts/{layoutId} and returns the API response. ^[2]

Step 4. (Optional) Delete individual sections within a layout first.

If you need to remove only a specific section rather than the entire layout, or if your workflow requires clearing sections before deleting the parent layout, use the section-level endpoint:

DELETE /api/v1/layouts/{layoutId}/sections/{sectionId}

Both layoutId and sectionId are required path parameters. An optional p dict can carry additional query parameters. ^[5]

Step 5. (Optional) Remove associated layout rules.

Layout rules that reference the layout you are deleting should be cleaned up separately. Use the layout rules endpoint:

DELETE /api/v1/layoutRules/{ruleId}

Pass the ruleId of each rule you want to remove. ^[6]

Step 6. Verify the deletion was successful.

After the API responds, issue a follow-up GET request to confirm the layout no longer appears in the list. A successful delete will result in the layout being absent from subsequent list responses.

Common pitfalls

• This action is permanent. The delete layout operation is classified as a high-risk, irreversible action — there is no recycle bin or restore option once it completes. ^[4] Always back up your layout configuration (e.g., document field mappings and section structures) before proceeding.

• Missing or incorrect scopes will block the request. If your OAuth token was generated without Desk.settings.DELETE or Desk.settings.ALL, the API will return an authorisation error. Re-check your scope configuration and regenerate the token if needed. ^[3]

• Deleting a layout does not automatically remove its rules. Layout rules are stored independently under /api/v1/layoutRules/{ruleId}. Orphaned rules may cause unexpected behaviour if not cleaned up separately. ^[6]

• Section deletions are scoped to the parent layout. When calling the section delete endpoint, both the layoutId and sectionId must be correct — passing a sectionId that belongs to a different layout will not produce the intended result. ^[5]

What to check

• Scope validity: Confirm your active OAuth token includes Desk.settings.DELETE or Desk.settings.ALL before making the call. ^[3]
• Layout ID accuracy: Double-check the layoutId value against a fresh GET response to ensure you are targeting the correct layout and not an active, in-use one. ^[2]
• Orphaned rules: After deleting the layout, query /api/v1/layoutRules to confirm no stale rules remain that referenced the removed layout. ^[6]