How to search within a specific module in Zoho Desk

Searching within a specific module in Zoho Desk via the API is straightforward: you call a dedicated endpoint that scopes results to a single module, rather than scanning across all modules at once.

Why this matters

When your Zoho Desk instance holds thousands of tickets, contacts, tasks, or articles, a broad search can return noisy, hard-to-filter results. Scoping your query to a single module — say, tickets or contacts — keeps responses lean and makes downstream processing much simpler. This is especially useful when building integrations, automations, or AI-assisted workflows on top of Zoho Desk's API. As a reminder, Beam Help is independent expert support for Zoho and is not official Zoho support.

---

Step-by-step

Step 1. Confirm your OAuth token includes the Desk.search.READ scope. Without it, the search endpoint will return an authorisation error. This scope sits alongside the other Desk scopes such as Desk.tickets.READ and Desk.contacts.READ in your OAuth configuration. ^[2]

Step 2. Identify the module you want to search. Common values include tickets, contacts, tasks, events, and articles — all of which have corresponding read/write scopes available in the Desk OAuth scope list. ^[2]

Step 3. Make a GET request to the module-scoped search endpoint:

GET /api/v1/{module}/search

Replace {module} with the lowercase module name you identified in Step 2 (for example, tickets or contacts). Pass your search parameters as query-string values in the p dictionary/object. ^[1]

Step 4. In Python, the call looks like this:

results = desk_api.search_in_module(module="tickets", p={"word": "billing issue"})

The searchinmodule method issues a GET request to /api/v1/{module}/search and forwards any parameters you supply as query arguments. ^[1]

Step 5. If you need results spanning *all* modules simultaneously, use the global search endpoint instead:

GET /api/v1/search

This searchacrossmodules operation accepts the same p parameter dictionary but does not require a module name in the path. ^[6] Use the module-specific endpoint (Step 3) whenever you want to narrow scope.

Step 6. To initialise the Zoho Desk API client correctly, ensure your connection object carries a valid deskorgid. The client is constructed with your API domain, access token, and org ID; if the org ID is missing, the system will attempt to auto-discover it by calling the organisations endpoint on first use. ^[7]

---

Common pitfalls

• Missing Desk.search.READ scope. This is a distinct scope entry and is easy to overlook when copying scope lists. Double-check that it appears at the end of your Desk scopes configuration. [^2,3]
• Wrong module name casing or spelling. The {module} path segment must match the Zoho Desk API's expected value exactly (e.g., tickets, not Tickets or ticket). An unrecognised module name will typically return a 404 or empty result set. ^[1]
• No org ID on the client. If deskorgid is blank when the client is instantiated, the first API call triggers an org-discovery lookup. This adds latency and can fail if the token lacks Desk.basic.READ. Make sure Desk.basic.READ is included in your scopes. [^2,7]
• Confusing module search with global search. The module-specific endpoint (/api/v1/{module}/search) and the global endpoint (/api/v1/search) are separate operations. Calling the global endpoint and expecting module-filtered results will not work as intended. [^1,6]

---

What to check

• Scope list: Verify that Desk.search.READ and the relevant module scope (e.g., Desk.tickets.READ) are both present in your OAuth configuration before making any search calls. ^[2]
• Endpoint path: Confirm the {module} placeholder in /api/v1/{module}/search is replaced with the correct, lowercase module name matching Zoho Desk's API conventions. ^[1]
• Org ID persistence: After the first successful API call, check that deskorgid has been stored in your connection record so subsequent requests do not incur the auto-discovery overhead. ^[7]