Hello everybody!
Query API lets you query for records based on queries using the CRM Object Query Language(COQL). COQL is based on the SQL query syntax, and supports the SELECT query to fetch records. Using this API, you can query for data across different modules that are linked using lookup fields.
1. Enhanced Field Limits in the SELECT Clause
You can now retrieve up to 500 fields in a single query. Previously, the limit was 50. This allows you to fetch more data in a single request, reducing the number of API calls and improving performance.
Sample query:
{ "select_query": "select Last_Name, Email, Phone, Industry, Revenue, ... (500 fields) from Leads where id is not null" } |
2. Enhanced Value Limits for IN and NOT IN Operators
The IN and NOT IN operators now support up to 100 values each, doubling the previous limit of 50. This enhancement allows for more comprehensive filtering in your queries. Users can now include a larger set of criteria in a single query, making it easier to retrieve your data without needing multiple queries.
Sample query for IN:
{ "select_query": "select Account_Name from Accounts where Industry in ('IT', 'Finance', 'Healthcare', ... (100 values))" }
|
Sample query for NOT IN:
{ "select_query": "select Account_Name from Accounts where Industry not in ('IT', 'Finance', 'Healthcare', ... (100 values))" } |
3. Custom View support in COQL API
No more manual filtering! Simply use a custom view ID directly in the
FROM clause. Retrieve custom view IDs using the
Custom View API and include them in your queries to retrieve specific-custom view data.
Unsupported Custom Views
- Custom View in Other Modules : The following custom views are not supported in any module.
- Shared By Me
- Co-owner
- Shared To Me
In the
Custom View API response for a module (e.g., Leads), search for the key
"system_name". If the value matches any of the unsupported custom views (Shared By Me, Co-owner, Shared To Me), that view is not supported.
Example : Shared By Me
Key and Value Structure | "system_name": "{module_name}SHAREDBYME" |
Example | "system_name": "LEADSSHAREDBYME" |
COQL supports CVID in the following format: FROM {module_API_name}#{CVID}.
See the sample query below for reference.
Sample query:
{ "select_query": "select Lead_Status from Leads#5725767000000087501 WHERE id is not null" } //CVID: 5725767000000087501 - This is the Custom View ID in the Leads module.
|
4. Retrieve Corresponding Field Metadata via COQL
Need to retrieve field details? You can
fetch both the required data and field metadata in a single query. Just add
"include_meta" key to your query to retrieve field metadata. This key fetches metadata for the fields specified only in the
SELECT column. Also, it eliminates making an additional
GET - Fields Metadata API call to know the field metadata and save API credits.
Sample query:
{ "select_query": "select Lead_Status, Phone from Leads where id is not null", "include_meta": [ "fields" ] } |
Ensure you have the ZohoCRM.settings.fields.READ scope to avoid an OAUTH_SCOPE_MISMATCH error.
Sample Response:
{ "data": [ { "Lead_Status": "Attempted to Contact", "Phone": "555-555-5555", "id": "5725767000000420480" }, { "Lead_Status": "Contact in Future", "Phone": "555-555-5555", "id": "5725767000000420481" }, . . . ], "fields": { "Lead_Status": { "webhook": true, "operation_type": { "web_update": true, "api_create": true, "web_create": true, "api_update": true }, "colour_code_enabled_by_system": false, "field_label": "Lead Status", "tooltip": null, "type": "used", "table_name": "CrmLeadDetails", "field_read_only": false, "required": false, "display_label": "Lead Status", "read_only": false, "association_details": null, "multi_module_lookup": {}, "id": "5725767000000002611", "created_time": null, "filterable": true, "visible": true, "refer_from_field": null "auto_number": {} } }, "info": { "count": 200, "more_records": true } }
|
5. Field Limit Restriction in the ORDER BY Clause
The fields limit has been restricted in the ORDER BY clause. You can specify up to 10 fields in the ORDER BY clause for more precise sorting. Previously, there was no limit. This restriction helps improve query performance.
sample query:
{ "select_query" : "select Last_Name from Leads where id is not null order by Lead_Source, Lead_Status, Email, ... (up to 10 fields)" } |
6. Duplicate fields restriction
Duplicate fields are restricted in ORDER BY, GROUP BY, and AGGREGATE clauses. That is, if the same field is specified multiple times within the same clause, leading to unnecessary repetition and potential errors. This ensures cleaner and more accurate query results. Previously, this restriction applied only to the SELECT column.
Bad query:
{ "select_query":"select id from Contacts where id is not null order by id,id" }
|
Duplicate aggregate fields in a query will result in a "DUPLICATE_DATA" error in the response.
7. Retrieve territory information
You can now retrieve territory information from a module by including the territory field API name in the SELECT column. This is useful to understand where your data has been distributed in various geographical locations.
Sample query 1 :
{ "select_query": "select Account_Name, Territories from Accounts where id is not null" } |
Sample query 2 :
{ "select_query" : "select Territories, Account_Name.Territories from Contacts where id is not null" } |
Sample response:
{
"data": [ { "Account_Name.Territories": [ { "name": "USA", "id": "5725767000000454003" } ], "id": "5725767000000420261", "Territories": [ { "name": "China", "id": "5725767000000454981" } ] }, . . . ], "info": { "count": 174, "more_records": false } }
|
Supported modules to retrieve territory details: Contacts, Accounts, Leads, and Deals.
Note:
The territory field API names differ by module:
- Accounts, Contacts, and Leads : Territories
- Deals : Territory
8. "Full_Name" retrieval based on user preferences
The
full name can be retrieved based on the current user's display name pattern, as set in their
preferences. This ensures that the full name format aligns with the user's settings.
The "Full_Name" field contains the concatenated values of the First_Name and Last_Name fields. This is a read-only field available only in the Leads and Contacts modules.
Sample query:
{ "select_query": "select Full_Name from Contacts where id is not null" } |
9. Support for Multiple Modules in "what_id"
A Multi-Module Lookup (MML) field is a special type of lookup field that allows you to establish a relationship between a record in one module and records from multiple other modules. Unlike a standard lookup field that references a single module, an MML field can point to multiple module types.
Currently, an MML field is available in the Appointments module. The Appointment_For field is an MML field that can reference multiple modules, such as Leads and Contacts.
Sample query:
{ "select_query": "select 'What_Id->Leads.Company','What_Id->Accounts.Account_Type' from Calls where id is not null" }
|
9.1 Support to query Multi-module Lookup (MML)'s inner field
You can now retrieve inner fields of linked modules within the MML field. This provides deeper insights into related fields data in a module.
For example, you can now query specific fields from a related module that is linked through a Multi-Module Lookup, making your data retrieval more precise and informative.
{ "select_query": "select 'Appointment_For->Contacts.Lead_Source' from Appointments__s where id is not null" } |
This query retrieves the
Lead Source field from the
Contacts module within the
Appointment_For MML field.
9.2 Support for Querying Multi-Module Lookup Module Name
Retrieve the module name associated with each record in a Multi-Module Lookup (MML) field. This helps in identifying the source module of the linked records, providing a better context for your data.
Sample query:
{ "select_query": "select Appointment_For.module.api_name, Appointment_For from Appointments__s where id is not null" } |
The
Appointment_For.module.api_name returns the module name (e.g., Contacts or Accounts) for each record linked in the
Appointment_For MML field.
10. Retrieving Consent-Related Information
You can now retrieve
consent-related information using the
Consents Lookup fields in a module. This is particularly useful for
GDPR compliance, ensuring you have consent records.
For more details, refer to the
Consent Management documentation. This is particularly useful for GDPR compliance, ensuring you have all necessary consent information.
Note:
- Once GDPR is enabled and configured for a module, a new Data Processing Basis Details field will be created in the respective module with the data type consent_lookup ("data_type": "consent_lookup").
- You can retrieve the Data Processing Basis Details field created in the module using the GET Fields Metadata API.
- To know all available fields in the Consents module, make another GET Fields Metadata API call.
Sample query:
{ "select_query": "select Data_Processing_Basis_Details.Contact_Through_Survey, Data_Processing_Basis_Details.Data_Processing_Basis from Leads where Data_Processing_Basis_Details is not null" }
|
11. Enhanced Lookup Field Response
Previously, when a lookup field was included in the SELECT column JOIN, only the lookup field’s ID was displayed. From V7, the corresponding display field value is also provided. Now, when you specify a lookup field in the SELECT column, the response includes the id of the Lookup record ID and the display field value of the lookup record.
This eliminates the need for an additional SELECT column JOIN to fetch the display value (e.g., Owner.last_name).
Sample query:
{ "select_query" : "select Owner from Accounts where id is not null" } |
Sample response
V6 | V7 |
{ "data": [ { "Owner": { "id": "5725767000000411001" }, "id": "5725767000000420169" },
{ "Owner": { "id": "5725767000000411001" }, "id": "5725767000000420170" }, . . . ], "info": { "count": 23, "more_records": false } } | { "data": [ { "Owner": { "name": "Boyle", "id": "5725767000000411001" }, "id": "5725767000000420169" },
{ "Owner": { "name": "Kate", "id": "5725767000000411482" }, "id": "5725767000000420170" }, . . . ], "info": { "count": 23, "more_records": false } } |
Note:
- If you query the Users lookup field in the SELECT column, the corresponding record’s last name (display field) will be displayed in the name key of the corresponding lookup JSON (e.g. Owner) response, from V7.
- Display field value will not be available for Consent Lookup and Multi-Module Lookup (MML) fields.
12. Increasing "Profile Image" field comparators
The Profile Image field now supports additional comparators.
V6 | V7 |
is null, is not null | is null, is not null, =, !=, in, not in, like, not like |
You can use a record image's ID to fetch related data. For example, if you only have a record image's ID and want to retrieve the respective record's last name, you can include the record image ID in your query.
Sample query:
{ "select_query" : "select Record_Image from Leads where Record_Image = 'siwz79472749456ff433f8b88d0a795ae9855' " } |
13. Enhanced "Rollup Summary" field comparators
The Rollup Summary field now supports additional comparators, making it easier to filter and analyze your data with more precision.
V6 | V7 |
is null, is not null | =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null |
Sample query:
{ "select_query" : "select Last_Name from Leads where Total_Calls between 5 and 10" }
|
13.1 Enhanced response for the Date and Datetime return types of the Rollup Summary
The Date and Datetime return types in the Rollup Summary field are now provided in ISO date and ISO datetime formats based on the user's time zone.
Sample query:
{ "select_query": "select Last_Note_Added from Leads where id is not null" } |
Response V6 | V7 |
{ "data": [ { "Last_Note_Added": "1721302770000", "id": "5725767000003160016" }, . . . ], "info": { "count": 200, "more_records": true } } | { "data": [
{ "Last_Note_Added": "2024-07-04T03:49:48-07:00", "id": "5725767000003160016" }, . . . ], "info": { "count": 200, "more_records": true } } |
14. Enhanced LIMIT and OFFSET Value Limit
You can now retrieve up to 100,000 records using pagination with the LIMIT and OFFSET clauses. This significantly increases the amount of data you can handle in a single query, making it easier to work with large datasets. Previously, the maximum limit was 10,000. For the next set of records, add another criteria id > {1,00,000th record ID} with the "AND" operator, and go on to fetch the next 1,00,000 records.
Sample query:
{ "select_query" : "select Last_Name, Created_Time from Leads where (Last_Name is not null and id > 5725767000003160016)" } |
15. Enhanced JOIN Support Limit
Base Column JOIN
If a query contains any lookup_field.{any_field} in any clause other than the SELECT column such as ORDER BY, GROUP BY, or AGGREGATE columns, then it will be treated as Base JOIN. The Base JOIN support limit has been increased from two to five. This enhancement enables more complex queries across multiple modules, improving data retrieval flexibility.
Sample query:
{ "select_query" : "select id from Contacts where id is not null order by Owner.role, Created_By.profile" } |
Refer to the
Base JOIN section in the COQL API document for more details.
15.1 Introducing the SELECT Column JOIN
A new SELECT column JOIN has been introduced, with a maximum limit of 15.
Advantages of SELECT Column JOIN
- If a lookup field is included in the SELECT column and another lookup field is used in the Base column JOIN, they will be treated as separate JOINs. This ensures that the SELECT column JOIN does not affect the Base JOIN.
- Previously, when two lookup fields in the SELECT pointed to the same module (e.g., Users), they were treated as separate JOINs. From V7, they are now considered a single JOIN, optimizing query performance and reducing redundancy.
Sample query:
{ "select_query" : "select Owner.last_name, Created_By.role from Contacts where id is not null" } |
16. Subquery in COQL
A subquery support has been given in COQL. A subquery is a child query that is nested or embedded within a parent query i.e., outer query. Subqueries can be used as an alternative to JOINs in a query. Use subqueries when a JOIN field is only needed in the criteria, i.e., in the WHERE clause. The primary reason for using subqueries is to improve performance by saving time and memory.
Sample query:
{ "select_query" : "select Lead_Source,Email from Leads where Contacts in (select id from Contacts where Email=' patricia@mail.com')" } |
You can retrieve up to 100 records per subquery in a single query. A maximum of 5 subqueries can be queried in a parent query.
Refer to the
Subquery documentation for more details.
A detailed post on Subquery will be covered in an upcoming Kaizen post.
We trust that this post meets your needs and is helpful. Let us know your thoughts in the comment section or reach out to us at
support@zohocrm.com.
Stay tuned for more insights in our upcoming Kaizen posts!
Recent Topics
Power of Automation:: Automate the process of updating project status based on a specific task status.
Hello Everyone, Today, I am pleased to showcase the capabilities of a custom function that is available in our Gallery. To explore the custom functions within the Gallery, please follow the steps below. Click Setup in the top right corner > Developer
ZOHO SHEETS
Where can I access desktop version of zoho sheets? It is important to do basic work If it is available, please guide me to the same
Attention API Users: Upcoming Support for Renaming System Fields
Hello all! We are excited to announce an upcoming enhancement in Zoho CRM: support for renaming system-defined fields! Current Behavior Currently, system-defined fields returned by the GET - Fields Metadata API have display_label and field_label properties
Billing Management: #3 Billing Unbilled Charges Periodically
We had a smooth sail into Prorated Billing, a practice that ensures fairness when customers join, upgrade, or downgrade a service at any point during the billing cycle. But what happens when a customer requests additional limits or features during the
No bank feeds from First National Bank South Africa since 12 September
I do not know how Zoho Books expects its customers to run a business like this. I have contacted Zoho books numerous times about this and the say it is solved - on email NO ONE ANSWERS THE SOUTH AFRICAN HELP LINE Come on Zoho Books, you cannot expect
Citation Problem
I had an previous ticket (#116148702) on this subject. The basic problem is this; the "Fetch Details" feature works fine on the first attempt but fails on every subsequent attempt, Back in July after having submitted information electronically and was
Open Sans Font in Zoho Books is not Open Sans.
Font choice in customising PDF Templates is very limited, we cannot upload custom fonts, and to make things worse, the font names are not accurate. I selected Open Sans, and thought the system was bugging, but no, Open Sans is not Open Sans. The real
Failing to generate Access and Refresh Token
Hello. I have two problems: First one when generating Access and Refresh Token I get this response: As per the guide here : https://www.zoho.com/books/api/v3/#oauth (using server based application) I'm following all the steps. I have managed to get
Zeptomail 136.143.188.150 blocked by SpamCop
Hi - it looks like this IP is being blocked, resulting in hard bounces unfortunately :( "Reason: uncategorized-bounceMessage: 5.7.1 Service unavailable; Client host [136.143.188.150] blocked using bl.spamcop.net; Blocked - see https://www.spamcop.net/bl.shtml?136.143.188.150
Apply transaction rules to multiple banks
Is there any way to make transaction rules for one bank apply to other banks? It seems cumbersome to have to re-enter the same date for every account.
How to bulk update records with Data Enrichment by Zia
Hi, I want to bulk update my records with Data Enrichment by Zia. How can I do this?
Need Guidance on SPF Flattening for Zoho Mail Configuration
Hi everyone, I'm hoping to get some advice on optimizing my SPF record for a Zoho Mail setup. I use Zoho Mail along with several other Zoho services, and as a result, my current SPF record has grown to include multiple include mechanisms. My Cloudflare
How do I split a large CSV file into smaller parts for import into Zoho?
Hi everyone, I’m trying to upload a CSV file into Zoho, but the file is very large (millions of rows), and Zoho keeps giving me errors or takes forever to process. I think the file size is too big for a single import. Manually breaking the CSV into smaller
Client Script Payload Size Bug
var createParams = { "data": [{ "Name": "PS for PR 4050082000024714556", "Price_Request": { "id": "4050082000024714556" }, "Account": { "id": "4050082000021345001" }, "Deal": { "id": "4050082000023972001" }, "Owner": { "id": "4050082000007223004" }, "Approval_Status":
Sync Issue Between Zoho Notebook Web App on Firefox (PC) and Android App
Hi Zoho Notebook Community, I'm facing a sync problem with Zoho Notebook. When I use the web version on Mozilla Firefox browser on my PC, I create and save new notes, and I've synced them successfully. However, these new notes aren't showing up in my
Messages not displayed from personal LinkedIn profile
Hello. I connected both our company profile and my personal profile to Zoho social. I do see all messages from our company page but none from my private page. not even the profile is being added on top to to switch between company or private profile,
lead convert between modules
Hello, The workflow we set up to automatically transfer leads registered via Zapier into the Patients module to the Leads module started to malfunction unexpectedly on September 25, 2025, at 11:00 AM. Under normal circumstances, all fields filled in the
Flow Task Limits - How to Monitor, Understand Consumption?
So, I got an email last night saying that I've exhausted 70% of my tasks for this month, and encouraging me to buy more tasks. I started to dig into this, and I cannot for the life of me figure out where to find any useful information for understanding,
Cross References Do Not Update Correctly
I am using cross references to reference Figures and current am just using the label and number, i.e. Figure #. As seen here: When I need to update the field, I use the update field button. But it will change the cross reference to no longer only including
Manage control over Microsoft Office 365 integrations with profile-based sync permissions
Greetings all, Previously, all users in Zoho CRM had access to enable Microsoft integrations (Calendar, Contacts, and Tasks) in their accounts, regardless of their profile type. Users with administrator profiles can now manage profile-based permissions
How to Track and Manage Schedule Changes in Zoho Projects
Keeping projects on track requires meticulous planning. However, unforeseen circumstances can cause changes to schedules, leading to delays. It becomes important to capture the reason for such changes to avoid them in the future. Zoho Projects acknowledges
Is there a notification API when a new note is addeding
Trying to push to Cliq, or email notification when there's a new note added in module. How to implement this?
Zoho Sheet - Desktop App or Offline
Since Zoho Docs is now available as a desktop app and offline, when is a realistic ETA for Sheet to have the same functionality?I am surprised this was not laucned at the same time as Docs.
Collaborate Feature doesn't work
Hello Team. It seems that the collaborate section is broken? I can post something but it all appears in "Discussions". In there is no way how I would mark something as Draft, Approval, post or any of the other filter categories? Also if I draft a post
Edit Permission during and after approval?
When a record is sent for approval Can a user request for edit permission from the approver? We don't want to give edit permissions for all the records under approval Only on a case-by-case basis How can we achieve this?
Zoho web and mobile application not workingn
Both zoho forms web and mobile application aren't working. I have checked my network connections and they are fine.
Introducing the revamped What's New page
Hello everyone! We're happy to announce that Zoho Campaigns' What's New page has undergone a complete revamp. We've bid the old page adieu after a long time and have introduced a new, sleeker-looking page. Without further ado, let's dive into the main
Prevent stripping of custom CSS when creating an email template?
Anyone have a workaround for this? Zoho really needs to hire new designers - templates are terrible. A custom template has been created, but every time we try to use it, it strips out all the CSS from the head. IE, we'll define the styles right in the <head> (simple example below) and everything gets stripped (initially, it saves fine, but when you browse away and come back to the template, all the custom css is removed). <style type="text/css"> .footerContent a{display:block !important;} </style>
Bulk Moving Images into Folders in the Library
I can't seem to select multiple images to move into a folder in order to clean up my image library and organize it. Instead, I have to move each individual image into the folder and sometimes it takes MULTIPLE tries to get it to go in there. Am I missing
Latest updates in Zoho Meeting | Breakout rooms and End to end encryption
Hello everyone, We’re excited to share a few updates for Zoho Meeting. Here's what we've been working on lately: Introducing Breakout Rooms for enhanced collaboration in your online meetings and End-to-end encryption to ensure that the data is encrypted
Systematic SPF alignment issues with Zoho subdomains
Analysis Period: August 19 - September 1, 2025 PROBLEM SUMMARY Multiple Zoho services are causing systematic SPF authentication failures in DMARC reports from major email providers (Google, Microsoft, Zoho). While emails are successfully delivered due
Accidentally deleted a meeting recording -- can it be recovered?
Hi, I accidentally deleted the recording for a meeting I had today. Is there a way I can recover it?
To Zoho customers and partners: how do you use Linked Workspaces?
Hello, I'm exploring how we can set up and use Linked Workspaces and would like to hear from customers and partners about your use cases and experience with them. I have a Zoho ticket open, because my workspace creation fails. In the meantime, how is
How to access email templates using Desk API?
Trying to send an email to the customer associated to the ticket for an after hours notification and can't find the API endpoint to grab the email template. Found an example stating it should be: "https://desk.zoho.com/api/v1/emailtemplates/" + templateID;
How to render either thumbnail_url or preview_url or preview_data_url
I get 401 Unauthorised when using these urls in the <img> tag src attribute. Guide me on how to use them!
Update Portal User Name using Deluge?
Hey everyone. I have a basic intake form that gathers some general information. Our team then has a consultation with the person. If the person wants to move forward, the team pushes a CRM button that adds the user to a creator portal. That process is
Zoho Bookings No Sync with Outlook
Zoho Bookings appointments are showing on my Outlook Calendar but Outlook events are not showing on Zoho Bookings. How do I fix this?
Unable to retrieve Contact_Name field contents using Web API in javascript function
Hello, I've added a field in the Purchase Order form to select and associate a Sales Order (Orden_de_venta, lookup field). I've also created a client script to complete some fields from the Sales Order (and the Quote), when the user specifies the related
Updating Woocommerce Variation Products Prices Via Zoho CRM
I can update product prices with this flow: But I can't update variant products. I got a code from Zoho for this, but I couldn't get it to work. It needs to find the product in the CRM from the SKU field and update the variation with the price there.
Emails Disappearing From Inbox
I am experiencing the unnerving problem of having some of the messages in my inbox just disappear. It seems to happen to messages that have been in there for longer than a certain amount of time (not sure how long exactly). They are usually messages that I have flagged and know I need to act on, but have not gotten around to doing so yet. I leave them in my inbox so I will see them and be reminded that I still need to do something about them, but at least twice now I have opened my inbox and found
Next Page