Kaizen #183 - COQL API's Enhancements in Zoho CRM API Version 7

Hello everybody!

Welcome back to another post in our Kaizen series.

In this post, we will discuss the latest COQL API enhancements introduced in Zoho CRM Version 7.

COQL API

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. 

Refer to the COQL document for more details.

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" }

Refer to the JOINs in COQL Queries for more details on both the JOINs.

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! 

Happy querying!

Previous Kaizen: Kaizen #182 - Queries in Canvas List View | Kaizen Directory

• Topic Participants

• Subramanian K

  

• Sticky Posts

• Kaizen #198: Using Client Script for Custom Validation in Blueprint

  Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

• Kaizen #226: Using ZRC in Client Script

  Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In this

• Kaizen #222 - Client Script Support for Notes Related List

  Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore how

• Kaizen #217 - Actions APIs : Tasks

  Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.

• Kaizen #216 - Actions APIs : Email Notifications

  Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are

• Recent Topics

• Option in pipeline deal to select which hotel or branch or store if client has more than one local store

  Hi, I would like to know if there is an option in the deal pipeline to select which hotel, branch, or store a deal is related to—if the company has more than one location. For example, I have a client that owns several hotels under the same company, and

• Request to Recover Deleted Task List – Project ID: RIV-MOD-10722

  Hi Zoho Team, I hope this message finds you well. My Zoho task list associated with Project ID: RIV-MOD-10722 appears to have been deleted. When I clicked on the task link from the email notification, I received the following message: "Task has been deleted

• Is this a SCAM email or is it really Zoho?

  L.S. I received the following message. Is this from Zoho? I have had a Zoho One account for many years and my website has been online for years. If it is a scam, I think you should know about it.

• Is it possible to use HTML formatting in SMS messages sent from Zoho?

  Hi everyone, I have a question regarding sending SMS from Zoho When we send emails from Zoho, we can include HTML code to format the message (like adding links, styling, etc.). Is it possible to do something similar when sending SMS messages through Zoho

• an issue in Zoho CRM where the workflow rule is not triggering

  H I’m currently facing an issue in Zoho CRM where the workflow rule is not triggering when a new lead is created through a webform. I’ve double-checked the criteria and field updates, everything seems fine but it still doesn’t fire. Has anyone faced this

• Email Insights included in Bigin emals are marked as SPAM everywhere

  Today I noticed that email recipients who use Office 365 never receive emails sent from Bigin. Further examination showed that all Email Insights links in email headers are marked as spam/phishing by Office 365. Example screen included. The problem is

• Email Parser Not Extracting Fields Correctly with Certain Label Formats

  I’ve been testing the Email Parser functionality in Zoho CRM to automatically extract data from incoming emails and map it to CRM fields. During testing, I noticed that parsing sometimes fails when the email contains field labels formatted like this:

• How do I import Connected Records for a Deal?

  Can you point me to an example of the CSV file that would add related records to an existing CRM Deal? I imported a Deal, then tried importing a connected record using a unique ID that references the Deal ID, but it doesn't attach it to the Deal rec

• File Upload Field in Zoho Forms Not Updating Existing File in Zoho CRM

  Hi everyone, I’m trying to understand the behavior of a file upload field mapped from Zoho Forms to Zoho CRM. Scenario There is a File Upload field in a Zoho CRM module. A Zoho Form also has a File Upload field, which is mapped to that CRM field. When

• Zoho Training

  Greetings! I am trainer. My focus area is Project Management and MS Project. I have used Zoho CRM to a good extent. Though, I was interested in using ZOHO projects, as there were no live projects, I could not take it up for studies. Recently a client

• Detailed list of scoring rules in Zoho CRM

  Good morning Zoho community, warm greetings The reason for my message today is that I have a problem with my CRM, which I will explain below: Our organization has scoring rules designed to rate our potential customers or leads in the application based

• How to create a summary document from Projects details

  Hi, Our team is creating many projects inside Zoho Project. When closing a project, they write a summary document containing data from the projects it-self (understand project budget, customers, etc...), and editable (ie the document is either a Writer

• Host in US Data Centre

  I humble apply to be registered on US Data centre

• convert the project to templet

  i have some deployment ME product for different customer , i need to create a fixed template for use it rather then keeping creating this template every time

• Best practices for managing Project Charters, Business Case and RAID logs within Zoho?

  Hello everyone, I’m currently refining our PMO setup within Zoho Projects and I’m curious how others are handling high-level governance documentation. We’ve been using the standardized Project Charter, Business Case and RAID frameworks from projectmanagertemplate.com

• Resource Management System built using Zoho CRM, Creator, Projects, and People:

  In a Resource Management System built using Zoho CRM, Creator, Projects, and People: CRM Deal Closed → Creator Allocation Engine → Zoho Projects Task Assignment What is the recommended architecture to handle dynamic reassignment when: an employee goes

• Dynamic Remaining Quantity in Lookup During Allocation

  Hi everyone, From what I understand in Zoho Creator, lookup fields only display the stored value from the source record and do not dynamically update while a form is being filled. Because of this, showing a real-time updated remaining quantity inside

• connect zoho creator with google drive

  Hello everyone, I need to connect to a folder drive. The idea, is that google drive loads a text document with some data, I must read that text document to be able to autofill a form that I have in zoho creator with that data. I also attach PDFs and place

• Ability to Attach Record-Specific Files Automatically in Workflow Email Templates

  Currently in Zoho CRM, email templates allow attachments to be added, but these attachments are static and remain the same for every recipient. There is no straightforward option to automatically attach a file that is stored within the specific CRM record

• Uploaded files are not included when using "Include user submitted data" in Email Notification

  In Send Email notification workflow in Zoho Creator, there is an option called "Include user submitted data" which allows the email to contain all the form submission details. However, when this option is enabled, files or images uploaded through File

• kanban view for client portal

  Are kanban views an option for client portals? Access to Kanban views in the client portals would solve some mobile-compliant issues I have with the UI. Kanban functions very nicely on mobile and would be a super asset for my clients and vendors as they

• Credit Card Pre-Authorization with later Capture/Settlement

  We really enjoy the convenience of being able to pay off a customer's invoice using our Auth.Net integration with Zoho Books. Unfortunately, we can only take advantage of this feature with a small percentage of our customers as it leaves a gaping hole

• Zoho Cliq not working on airplanes

  Hi, My team and I have been having this constant issue of cliq not working when connected to an airplane's wifi. Is there a reason for this? We have tried on different Airlines and it doesn't work on any of them. We need assistance here since we are constantly

• Zoho Sign 2025–2026: What's new and what's next

  Hello! Every year at Zoho Sign, we work hard to make document signing and agreement execution easy for all users. This year we sat down with our head of product, Mr. Subramanian Thayumanasamy, to discuss what we delivered in 2025 and our goals for 2026.

• Work Orders / Bundle Requests

  Zoho Inventory needs a work order / bundle request system. This record would be analogous to a purchase order in the purchasing workflow or a sales order in the sales cycle. It would be non-journaling, but it would reserve the appropriate inventory of

• Izettle or Sumup Integration for Zoho Books.

  The Stripe & Square clearing works great in Zoho Books. Any further integrations planned in the future for Izettle or Sumup? These card processors are very common for taking payments with a card reader.

• Train Zoho Answer Bot Based on Customer

  Hi all, Is it currently possible to mark Help Centre articles to a specific customer, and restrict the answer bot to only use relevant information if it is either marked as "General", or tagged for the specific customer in question? We currently have

• Trying to access records in a custom module in Zoho Desk and not having luck

  I've built a custom module in Zoho Desk and am using a custom function to query the records in the module and I'm not having any luck. The only way I have found to retreive a record is by getting it by its recordID (the long zoho assigned one). The function

• Composite items inside of composite items; bill of materials needed

  Hi Zoho and Everyone, I am evaluating whether Zoho Inventory will work for my small business. I grow and harvest herbs and spices but also get from wholesalers. I use all these items to make herbal teas, but also sell them as individual items on my Shopify store and Etsy. I discovered the composite item bundling and am wondering if I could get some assistance since there is no bill of materials: Our herbal company's best selling tea is a sleepytime tea. Sleepytime Tea can be purchased in three weights

• ZOHO Books Smart Accounting Software for Travel Agency

  Dear Travel partner, Contact for Travel Agency Accounting Setup & Training Vansh Travel (ZOHO Books Authorised partner) Email: info@vanshtravel.com Mo: +91 98984 95155 Please find PDF   

• 452 Mailbox delivery restricted by policy error

  We have been testing Zoho desk for about a week now and have been forwarding emails in via an Exchange Online Mail flow rule without issue until yesterday. Suddenly yesterday morning we started getting the vast majority of the emails stuck in Pending

• Send Email reply on behalf of Agent

  Hi, When using the send email reply via the API I can set the reply on behalf of the customer by using impersonatedUserId in the header of the API call. Is there a way to do this for Agents too? I need to be able to send an email reply on behalf of an

• Sharing Tickets to a team within a department

  Hi there, We have a need for one department to be able to share tickets to a specific team within a department, I'm wondering if this is possible? All the shared tickets are going into the 'Shared Tickets' view for the whole department but is there a

• Removing To or CC Addresses from Desk Ticket

  I was hoping i could find a way to remove unnecessary email addresses from tickets submitted via email. For example, a customer may email the support address AND others who are in the helpdesk notification group, in either the TO or CC address. This results

• Do not use isnull()

  Does not always return booleans. Can also return null. Never use this function. Just use var==null instead.

• Organization wide Account and Contacts Visibility/Sharing Capabilities?

  Has anyone figured out a way to make visibility or sharing of Accounts and Contacts to be available across the entire organization without having to have every individual user edit their Sharing permissions? For our sales folks they need to be able to

• Is there a way to configure dark mode for Campaigns emails that go out to customers?

  I've found a lot of information on how to configure dark mode for my (The user) personal Zoho workspace and email, but is there any way to edit dark mode settings on emails that we send out to customers via campaigns?  We sent out a test email the other

• When Does WorkDrive integrate with Books?

  When Does WorkDrive integrate with Books?

• FSM integration with Books

  Hi, I have spent a few months working with FSM and have come across a critical gap in the functionality, which I find almost shocking....either that, or I am an idiot. The lack of bi-directional sync between Books and FSM on Sales Orders/ Work Orders

• How to close an estimate ?

  Hello, I have created estimates, and converted them to invoices to get 50% payment. Now I have 2 cases where the estimate stills shows status partially invoiced, however: 1. for one of them, project stopped half way, so the remaining part will never be

• Next Page