How to delete a custom module in Zoho Desk

Deleting a custom module in Zoho Desk is a permanent, irreversible action performed via the Zoho Desk REST API using a single authenticated DELETE request targeting the module's unique identifier.

Why this matters

Custom modules in Zoho Desk can accumulate over time as your support workflows evolve, and stale or unused modules create clutter in your portal configuration. If you are programmatically managing your Desk environment — for example, during a migration, a cleanup script, or an automated provisioning workflow — you need a reliable, API-driven way to remove these modules safely. Understanding the exact endpoint and required OAuth permissions beforehand prevents costly mistakes.

> Beam Help is an independent expert support resource, not official Zoho support. Always back up your module configuration and data before executing destructive operations.

---

Step-by-step

Step 1. Confirm your OAuth scopes are in place.

Before making any destructive API call, verify that your connected OAuth token includes the Desk.settings.DELETE scope (and ideally Desk.settings.ALL). Without this, Zoho Desk will reject the request with an authorisation error. Your token configuration should include the full settings scope family: Desk.settings.ALL, Desk.settings.READ, Desk.settings.WRITE, Desk.settings.CREATE, Desk.settings.UPDATE, and Desk.settings.DELETE. ^[3]

Step 2. Retrieve the moduleId of the custom module you want to remove.

You cannot delete a module without its internal identifier. Use a GET request against the Zoho Desk modules endpoint to list all modules and locate the moduleId for the target module. Record this value carefully — it is the only path parameter required for the delete operation. ^[1]

Step 3. Delete any custom fields attached to the module first (recommended).

While the API does not explicitly mandate this order, it is good practice to remove custom fields before deleting the module itself. To remove a custom field, issue a DELETE request to:

DELETE /api/v1/organizationFields/{moduleName}/{fieldId}

Supply the moduleName (the API name of your custom module) and the fieldId of each field you wish to remove. Repeat for every custom field associated with the module. ^[2]

Step 4. Issue the DELETE request to remove the custom module.

Send an authenticated HTTP DELETE to the following endpoint, substituting your module's identifier:

DELETE /api/v1/modules/{moduleId}

The only required path parameter is moduleId. An optional query parameter object p can be passed if your integration layer requires it, but for a straightforward deletion it is not needed. ^[1]

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

response = desk_client.delete_custom_module(moduleId="your_module_id_here")

^[1]

Step 5. Confirm the deletion.

After receiving a successful response (typically HTTP 200 or 204), attempt a GET request for the same moduleId. A 404 or equivalent "not found" response confirms the module has been fully removed from your Zoho Desk organisation. ^[1]

Step 6. Clean up any records that belonged to the module (if applicable).

If your workflow requires explicitly deleting individual records before removing the module, use the record-level DELETE endpoint:

DELETE /api/v1/{moduleName}/{recordId}

Pass the moduleName and the recordId for each record. This is particularly relevant if your integration tracks record IDs externally and needs to reconcile them after the module is gone. ^[7]

---

Common pitfalls

• Missing OAuth scope. The Desk.settings.DELETE scope must be present in your token. A token scoped only to Desk.tickets.ALL or Desk.contacts.READ will not have permission to modify module-level settings. Re-authorise your OAuth client with the correct scopes if you receive a permissions error. ^[3]

• Deleting a non-custom (system) module. The delete endpoint is intended for *custom* modules only. Attempting to delete a built-in Zoho Desk module (such as Tickets or Contacts) will result in an API error. Always confirm the module was user-created before proceeding. ^[1]

• Orphaned custom fields. Removing the parent module without first cleaning up its custom fields may leave orphaned field definitions in your organisation settings. Use the DELETE /api/v1/organizationFields/{moduleName}/{fieldId} endpoint proactively to avoid this. ^[2]

• No undo. There is no recycle bin or restore mechanism for deleted custom modules via the API. Treat this operation as permanent and ensure you have exported any data you need to retain before executing the request. ^[1]

---

What to check

• Scope verification: Confirm your OAuth token includes Desk.settings.DELETE or Desk.settings.ALL before running the delete call. ^[3]
• Module ID accuracy: Double-check the moduleId value against a fresh GET response immediately before deletion to avoid removing the wrong module. ^[1]
• Field cleanup: Verify that all custom fields associated with the module have been removed or accounted for using the organizationFields endpoint. ^[2]