Creating a query in Zoho CRM's Developer Hub lets you define reusable, filterable data-fetch operations against CRM modules, external databases, or third-party REST APIs — all from a single configuration interface.
Why this matters
When you need to pull specific subsets of CRM data programmatically — for example, all open deals linked to a particular contact — hardcoding API calls in every integration quickly becomes unmanageable. Zoho CRM's Queries feature gives you a named, versioned query you can reference across functions, widgets, and client scripts without duplicating logic. [1] As an independent expert team (Beam Help — not official Zoho support), we find this feature especially valuable when building dashboards or automation that depend on consistent, filtered record sets.
---
Step-by-step
Step 1. Navigate to Setup → Developer Hub → Queries. The Queries window will open, listing any queries already defined in your org. [1]
Step 2. Click Add Query to open the creation dialog. [1]
Step 3. In the Create Query pop-up, fill in a human-readable Query Name and an API Name (used when referencing the query programmatically), then click Next. [1]
Step 4. Under the Configuration section, the default source type is Zoho CRM Module. If you need a different source — such as a REST API endpoint, a self-hosted relational database (MySQL, Microsoft SQL, PostgreSQL), or a cloud database (Amazon RDS, Google Cloud Platform, Microsoft Azure) — click Change to switch the source type. [1][7]
Step 5. Select the CRM module you want to query. Note that subforms are also supported as queryable targets, giving you granular access to line-item data within records. [1]
Step 6. If the chosen module contains lookup fields, you can pull in related data by selecting up to two related modules from the Related Module drop-down. [1]
Step 7. Choose the specific fields you want returned from the Fields drop-down. You may select a maximum of 50 fields per query. [1]
Step 8. Configure the Criteria section. You have three options: [1]
- None — returns all records with no filtering applied.
- Record ID — filters the response to a single record by its unique identifier.
- Criteria — applies conditional logic across one or more fields. You can combine conditions using AND / OR operators and use comparators appropriate to each field type.
Step 9. For any criterion, decide whether to supply a static value (fixed at query-creation time) or a dynamic value. Choosing dynamic means the actual value is passed in at runtime — for instance, when the query is invoked from a function or widget — making the query reusable across different records or contexts. [1]
Step 10. Save the query. It will now appear in the Queries list and can be referenced by its API name from Zoho CRM Functions, Client Scripts, Widgets, or server-side SDK calls. [1][8]
---
Common pitfalls
- Related module limit: You can only include data from a maximum of two lookup-related modules in a single query. Attempting to add more will not be permitted in the configuration UI. [1]
- Field count ceiling: Selecting more than 50 fields in a single query is not allowed. If you need more fields, consider splitting the logic across two separate queries. [1]
- External database sources — IP whitelisting: When using a self-hosted MySQL, PostgreSQL, or Microsoft SQL database as a query source, you must whitelist Zoho CRM's IP addresses on your relay server, and add the host to Trusted Domains if it is not expressed as a raw IP address. Skipping this step will cause connection failures. [7]
- SSL and advanced configuration: For both standard and cloud databases, options like connection timeout, time zone, and SSL enforcement live under Advanced Configuration within the source setup — easy to overlook if you move through the wizard quickly. [7]
- Dynamic vs. static values: A common mistake is setting a value as static during testing and forgetting to switch it to dynamic before deploying. A static criterion will always filter on the same hard-coded value, which is rarely the intended behaviour in production workflows. [1]
---
What to check
- Query returns expected records: After saving, use the built-in test/preview option to confirm the criteria logic produces the correct filtered result set before wiring the query into any automation.
- API Name is unique and correctly referenced: Verify the API name you assigned matches exactly what is referenced in any Functions, Client Scripts, or SDK calls consuming this query. [1][8]
- Source connectivity (for external sources): If your query targets an external REST API or database, confirm the connection is active and that Zoho CRM IPs are whitelisted on the remote host before going live. [7]