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

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! 






    • Recent Topics

    • Announcing Agentic AI - Ask Zia!

      We are delighted to roll out the new agentic AI capabilities in Ask Zia, where every stage of the BI workflow is assisted by AI. With a human-in-the-loop approach, Ask Zia ensures that you’re in command of the decision, while AI handles the complexity.
    • Zoho People LMS VS Zoho Connect Manuals VS Zoho Learn

      in the past I came accross Zoho WIKI but did not like the platform because it could use a lot of upgrade. Over the time I have noticed Zoho People come out with a LMS module which allows us to created a shared knowledge for our internal team I also came across Zoho Connect which as a knowledge-based for internal team referred to as Manual Now I am seeing Zoho Learn which is a new and fine-tuned version of Zoho Wiki. All of these platforms are very similar but I am wondering what are the differences
    • Marketing Automation Activities in Zoho CRM

      Hello, I've connected Zoho CRM and Marketing Automation, sent a campaign, but no data are displayed in CRM, neither in "campaigns" section inside contact profile. It is possible to display Marketing Automation activities in CRM? Also in CRM Timelines?
    • How do we get a follow up to Experts 22: Scale up your customer support with integrations & extensibility

      Hi, How do we get a followup and answers to the questions we have asked during 'Experts 22: Scale up your customer support with integrations & extensibility'. I have repsonded to the answers but have no way of following up. Thanks Brett
    • Frustrating Email Duplication and Timeline Issues Between Zoho Mail and CRM

      Hi Zoho team, Can someone please help clarify what’s going on here? Here’s what’s happening: I initiate an email to a lead using Zoho Mail. The lead is created in Zoho CRM via the integration, and the email is correctly associated with that lead. Sometimes,
    • Best Strategy to import contacts and when to create leads

      Hi, I'm new to Bigin and looking for a "best" strategy. I had and have the following idea for an use case: 1. Search for websites which I want to contact 2. Create a contact in Bigin with all the required information based on this website (via API if
    • Better implementation of Item Category on Invoices and Estimates

      1) I have added Item Category as a custom field. Honestly, this should be a native part of the item itself, and either required, optional, or not used.  2) When entering an item on an invoice, you have to enter the first character(s) of the item, otherwise
    • Bulk Update (via the 'Accountant' menu)

      Why can't we bulk update Expenses to Owner's Drawings? It always ends in failure with the error "Involved account types are not applicable". If such conversion isn't possible, why make the option available? Better to allow it though.
    • Set Reply_to parameter for "Email an Invoice" API Endpoint

      Is there a way to set "Reply To" email address when using the Email an invoice API endpoint? It doesn't seem to be in documentation, but sometimes there are undocumented parameters. If it doesn't exist, please consider adding it as parameter since all
    • Zoho Books adaptado a la legislación española. ¿Sustitutos?

      Buenas a tod@s No tenemos información sobre la adaptación de Zoho Books a la nueva ley de facturación en España. Me preguntan usuarios de zoho que deberían hacer. Propongo una lista de alternativas, si al final se opta por no desarrollar la funcionalidad
    • A Question about Email Handling (Sending and Receiving)

      Hello! I was looking into setting up Email Aliases for my domain that I purchased a while ago through Zoho Mail. I set up a singular alias already and have it linked with Gmail, and it seems to be working out well. However, I set up another alias today,
    • Kaizen #201 - Answering Your Questions | Webhooks, Functions, and Schedules

      Hello everyone! Welcome back to another post in the Kaizen series! We are incredibly grateful for all the feedback we received, and as promised, we will answer all the queries in this Kaizen series. Last week, in our 200th post, we addressed one of the
    • Zoho Projects Strict Dates for Tasks

      Hi Zoho Projects team, I would love to see a feature to allow Strict Dates for Tasks. Sometimes in projects you have dates which must not move, even if predecessor Task dates change. For example, perhaps you need to book access to a facility to perform
    • No Mark as filed buton in GSTR -3b

      We are filing our GST in GST portal -and want to mark GST in Zoho books as filed. It is possible to mark GSTR 1 as filed through Mark as filed button. But there is no such button in GSTR-3B.  How to mark corrosponding GSTR-3B as filed?
    • ranking by drag the choices instead of rank by number

      is the option of draging the choice is available instead of selecting the ranking number for each choice?
    • TASKS - Dashboard to show ALL Tasks from ALL apps.

      The Unified Tasks View is useless without the other main zoho apps (Desk, Books & even FSM now) We need to see all our tasks under on pane of glass. The Zoho developers are out of touch with real business workflows. So how it was designed they want us
    • Function #13: Transaction level profitability

      In Zoho Books, the Profit & Loss report provides valuable insights into the overall profitability of your business, indicating whether you have made a profit or incurred a loss. However, there may be occasions when you wish to assess whether a specific
    • Zoho CRM with Sap Business One

      I need information about integration CRM with Sap BO, thank.
    • Allow bill to nest multiple projects

      A bill (purchase) is more often than not used across multiple projects and this functionality is missing and very urgently needed for accurate reporting of purchases across projects
    • Amazon invoice in Zoho Books

      I have just made my first few sales on Amazon India. Amazon Seller account generates invoices for the sales made on Amazon. These invoices are sent to customers also. Now when I was only making offline sales, I used to create Invoices in Zoho Book. Now
    • How can I change iOS display setting at night?

      It seems like at night the two light daytime settings themes (white with blue on top or just white) are not available and I am forced to choose among a few other colours that I really don’t want, I.e., black, blue or orange. Is there a way for me to always
    • Celebrate WWW day with Zoho Desk

      Let's recall the times when we learned 'WWW' stands for World Wide Web. Whether you like to call it wuh-wuh-wuh or double-u double-u double-u, or World Wide Web, we all owe a lot to this groundbreaking invention that reshaped how we connect, communicate,
    • The power of camaraderie

      In the days before the internet boom, conversations happened face-to-face or over the phone. Phone calls were precious; every minute counted, and every word mattered. We looked forward to those moments of real connection. Even today, nothing quite matches
    • Message Content is missing/invalid fault

      We cannot create a complete template over zoho. Some features - like button adding - is missing. The templates are created on Zoho and edited on Meta to solve the problem. But still then, some features cannot be used and the message returns this failure
    • Können bereits gesendete Kampagnen im Nachhinein einer Mailing-Liste zugeordnet werden, ohne dass die Kampagne erneut versendet wird?

      Wir haben unsere älteren Kampagnen in Campaigns über Kontaktkategorien versendet. Dann haben wir umgestellt auf Mailing-Listen, damit alte Kampagnen auch in einem Archiv aufgerufen werden können. Jetzt ist die Frage, ob die Kampagnen, die über die Kategorieauswahl
    • Newsletter Templates Are Not Mobile Responsive

      Hi, I've already submitted this request to ZOHO once this morning, but for some reason your system logged me out, wouldn't accept my username/password login, and isn't showing any evidence that I've submitted this issue. So here we go again... I am under the impression that your newsletter templates are supposed to be mobile optimised: https://www.zoho.com/campaigns/blog/responsive-email-marketing.html This is clearly not the case, as the last 2 newsletters I've created in Campaigns look perfect
    • Digest Juillet - Un résumé de ce qui s'est passé le mois dernier sur Community

      Bonjour à toutes et à tous, Zoom sur les nouveautés de juillet dernier au sein de Zoho Community France. Zoho Commerce vous propose une expérience améliorée grâce à sa nouvelle interface ergonomique et à ses fonctionnalités avancées, conçues pour faciliter
    • 100 Rows in a Subform is too limited

      We have a custom Module in CRM called Price Sheets, when we get a PO from a client we add the items from the PO to it and then check with our vendors for pricing and add our margin etc And after it is complete we have setup custom scripts to create a
    • Uninstall unattended agent

      Hello, I'm testing many use case before we purchase assist for our remote support. While we are testing what is the proper way to uninstall agent?  I did uninstall from systray, from windows control panel but still ZohoURservice is running. How can I uninstall client side?
    • Zoho Commerce Down?

      Is anyone else's storefront down at the moment? Ours has been down for at lease an hour.
    • Zoho Projects iOS app update: Dashboard widget on the home screen

      Hello everyone! We are excited to introduce the 'Dashboard' widget in the latest version(v3.10.8) of the Zoho Projects iOS app. Dashboard widgets allow you to view the project progress visually without having to open the app. The widget enables you to
    • Idea: Workflow Rule Trigger Only When Subform Row Is Updated (Thanks to New Inline Row Feature)

      Hi Zoho team and community, With the recent update to Zoho CRM, we can now add or delete rows inside subforms without entering edit mode, using the inline Add row button. This is a fantastic improvement for user experience — seamless, fast, and efficient.
    • Auto add new section based on document choices

      Hi team, I'm wondering if the below is a possilibity within Zoho sign. We have an application process to become a customer of ours, we currently use Zoho Sign to manage this application and this works quite well. However, if the customer indicates 'YES'
    • Change rate after xxxx kilometers

      Is there a way to change the miileage rate after a certain mileage. After 5000 kilometers, we want the rate to automaticly change. Thank !
    • Subform Entry Limit from a Subform Field (A different Subform on the same Form)

      Hi, I would like to be able to use a Subform 1 Field as the Dynamic Entry Limit for Subform 2. Even better would be able to use some code with the values, so for example using the Subform 1 Qty Field as the Max Entry limit for Subform 2, BUT only the
    • Slow Zobot response time

      Hi, We launched the Zobot on our site to sit along with the regular Live Chat but had to take the Zobot down as the response time was very slow. The bot was slow to begin then once the chat had been initiated the response was very slow. The bot typing
    • how to show data of 3 table in pivot

      Based on engineer name i want to get the data from 3 different tables like Service , amc, installation , but Every table contain Engineer name As Common , based that from the service table i want to take service amount , and count of service based on
    • Custom Status for Purchase Orders

      Currently Zoho books has functionality to create custom statuses for Sales Orders. Can this be extended to include custom status for purchase orders as well? It was a great decision to add this functionality to sales orders. Our use case is for tracking
    • Ask the Experts 22: Scale up your customer support with integrations & extensibility

      Hello everyone! The foundation is set. Build the beams. Raise the pillars. Set the walls. The Zoho Desk architecture stands tall. Let's discuss integration within Zoho Desk, extensions from the Marketplace, creating connections between Zoho Desk and other
    • Is there no way to duplicate an entire workflow or even custom function across multiple departments?

      Is there no way to duplicate an entire workflow or even a custom function from one department to other departments, like it is done for field duplication from one department layout to other department layouts?
    • Next Page