Variables in Zoho CRM Queries let you inject dynamic values at runtime, making a single saved query reusable across many different contexts without rewriting it each time.
Why this matters
When you build a query in Zoho CRM, hard-coded filter values limit its reuse. Variables solve this by acting as placeholders that are filled in at the moment the query runs — for example, passing a specific Contact ID or Stage value from a Canvas component or an API call. Understanding how to declare and use them correctly saves significant development time and keeps your query library lean. [5]
---
Step-by-step
Step 1. Navigate to the Queries section by going to Setup → Developer Hub → Queries. The Queries window will open, listing any existing queries you have already created. [2]
Step 2. Click Add Query to begin building a new query. In the Create Query pop-up, enter a Query Name and an API Name, then click Next. [2]
Step 3. Under Configuration, the default source type is Zoho CRM Module. If you need a different source type (such as COQL or REST API), click Change to switch. Select the CRM module you want to query. If the module contains lookup fields, you can include related modules via the Related Module drop-down — note that a maximum of two related module fields are permitted here. [2]
Step 4. From the Fields drop-down, select the fields you want the query to return. You may select up to 50 fields in a single query. [2]
Step 5. Under Criteria, choose how you want to filter records. The options are None (no filter), filter by Record ID, or apply custom Criteria using comparators combined with AND/OR operators. This is where variables become essential: instead of typing a fixed value for a criterion, choose the dynamic value option. A dynamic value signals that the actual data will be supplied when the query is executed elsewhere in your CRM setup. [2]
Step 6. Declare your variable using the required syntax. Wherever you want a dynamic value — inside a criteria field, a COQL statement, a REST API endpoint, or a parameter value — type the variable name wrapped in double curly braces: {{VARIABLE_NAME}}. This is the only accepted format; any deviation will prevent the variable from being recognised at runtime. [1][5]
Step 7. Variables are supported across multiple query locations: criteria values, COQL statements, endpoint URLs, and other parameter fields. When you later associate the query with a component such as a Canvas view, you will be prompted to map each declared variable to the appropriate field or data source so the runtime value can be passed in correctly. [5]
Step 8. Once your query and variables are configured, click through to save. You can revisit the query at any time from the Queries tab. To adjust the response structure, hover over the query, click the three-dot icon, and select Manage Schema — this lets you edit field types and labels in the query output without rewriting the query itself. [1]
---
Common pitfalls
- Wrong variable syntax. Variables must be written as
{{VARIABLE_NAME}}— single braces, square brackets, or any other format will not work. Double-check every placeholder before saving. [1][5] - Unmapped variables at association time. If you attach a query containing variables to a Canvas component or another CRM feature but forget to map each variable to a source field, the query will fail at runtime because no value is supplied. Always verify the mapping step after associating a query. [5]
- Exceeding field or lookup limits. Selecting more than 50 fields or more than two related module lookups will cause the query configuration to be rejected. Plan your field selection before building criteria. [2]
- REST API source prerequisites. If you are using a REST API source type rather than a CRM Module, you must first add the external host to Trusted Domains and whitelist Zoho CRM IPs on your relay server before the source can be validated and saved. [5]
---
What to check
- Variable syntax is correct — confirm every dynamic placeholder in your query follows the
{{VARIABLE_NAME}}double-curly-brace format before saving. [1] - Variables are mapped — after associating the query with a Canvas or other component, open the mapping configuration and verify each variable resolves to a live data field. [5]
- Schema reflects your needs — use Manage Schema to confirm field types and labels in the query response match what the consuming component expects, especially if you have edited the schema after initial creation. [1]
---
*Beam Help is an independent expert support resource for Zoho products and is not official Zoho support. For platform-level issues, always raise a ticket directly with Zoho.*