How to search records in Zoho

Searching records in Zoho CRM lets you quickly locate contacts, leads, deals, or any other module data using criteria-based filters — here's how to do it effectively.

Why this matters

When your CRM holds thousands of records, manually scrolling through lists is impractical. Knowing how to construct a proper search query means you can instantly surface the exact records you need — whether that's all leads created last week, contacts at a specific company, or deals above a certain value. This is especially useful when building automations or auditing data quality. As an independent expert support resource (not official Zoho support), Beam Help walks you through the mechanics below.

Step-by-step

Step 1. Identify the module you want to search. Zoho CRM organises data into modules such as Leads, Contacts, Deals, Accounts, and more. Before constructing your search, confirm the exact module name — it must match the CRM's internal naming (e.g., Contacts, not Contact). ^[6]

Step 2. Use the searchrecords tool (or equivalent API call) and pass the module parameter along with a criteria string. The criteria string follows a structured format using field names, operators, and values. For example, to find all contacts whose email address belongs to a particular domain, your criteria would look like (Email:endswith:@gmail.com). ^[6]

Step 3. For date-range searches, use the between operator in your criteria. For instance, to retrieve leads created during a specific week, structure your criteria as (Created_Time:between:YYYY-MM-DD:YYYY-MM-DD), substituting the actual start and end dates. This is particularly useful for weekly or monthly pipeline reviews. ^[6]

Step 4. If you only need a count of matching records rather than the full list, use the getrecordcount tool with the same module and optional criteria parameters. The system will return a plain-language result such as "You have 42 records in the Contacts module matching that filter." ^[4]

Step 5. Once results are returned, each matching record can be accessed directly via its CRM URL. The link format follows the pattern https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}, where dc is your data centre region (e.g., com, eu, in) and RecordId is the unique identifier of the record. ^[1]

Step 6. Ensure your connected OAuth credentials include the correct scopes for search operations. The ZohoCRM.coql.READ scope is required for query-based searches, and ZohoCRM.bulk.ALL covers bulk record retrieval. Without these scopes authorised, search requests will fail with a permissions error. ^[2]

Step 7. If your API connection returns no results or an authentication error, the system will attempt to refresh your access token automatically using the stored refresh token. If the refresh fails (for example, because the token has been revoked), you will need to reconnect your Zoho CRM account. ^[3]

Common pitfalls

• Wrong module name casing: Module names are case-sensitive in the criteria and parameters. Using contacts instead of Contacts can cause the search to return zero results or an error. Always use the capitalised form as shown in your CRM's module list. ^[6]

• Missing OAuth scopes: If ZohoCRM.coql.READ is not included in your authorised scopes, search queries will be rejected. Review your connected app's scope configuration and re-authorise if necessary. ^[2]

• Malformed criteria syntax: The criteria string must follow the exact format (FieldName:operator:value). Common mistakes include missing parentheses, using spaces around the colons, or referencing a field name that doesn't exist in the module. For date ranges, both a start and end date are required with the between operator. ^[6]

• Expired or missing tokens: If the stored access token has expired and the refresh token is also invalid, the API instance will return null and no search can be performed. In this case, the connection must be re-established from scratch. ^[3]

What to check

• Confirm the module name matches exactly what Zoho CRM uses internally (e.g., Leads, Contacts, Deals) before running your search. ^[6]
• Verify OAuth scopes include at minimum ZohoCRM.coql.READ to allow criteria-based record searches. ^[2]
• Test the direct record URL using the format https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId} to confirm the returned record IDs resolve correctly in your browser. ^[1]