COQL API's Enhancements in Zoho CRM API Version 7

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

        • Market Automation is hung in sync with crm in zoho one

          Sync between Market automation and crm stuck in loop. MA says they are connected, but does not allow module selection, building of lists, etc. can not go back around and disconnect and restart. Does not show in "Connected Apps", yet when you ty to connect

        • Currency Field Does Not show commas upon entry - leading to inaccurate entries!

          Hello Zoho.. When our sales reps are entering deals and the profit/revenue it is difficult to accurately enter numbers with lots of zeros when there commas are NOT added until the record is saved. Could commas be added to this filed type as it is being

        • Field of Lookup Module 2 Way Dynamic Connection

          I have several lookup fields in my custom Module And I have added fields from lookup fields to my module In my account module, I have a field called Quarterly Revenue Forecast But this is only one way i-e the field value is only fetched during record

        • Kaizen #116 - Client Types in Zoho API Console

          Hello everyone! Welcome back to another post in the Kaizen series! This week, we will discuss different client types available in Zoho API Console, and when to use each. When you register an app in Zoho API Console, you typically choose a client type

        • Used Car Inventory Tracker

          I need a to create an inventory database that has detailed information about each car we have in our inventory. Specifically, I need to know exactly how much labor and parts we have into each car as well as the cars purchase price, VIN, color, year, source etc. Budget : Negotiable | Duration : 1 week To leave a private message, please click the link for private response in post Action section.

        • Create Funnel to Track Email Outreach Conversion

          Hello, We would like to create a funnel that measures: N° of emails sent -> N° of emails opened -> N° of emails responded We would like to measure this email response conversion rate for each of our SDRs. We use the analytics tool of Zoho CRM and not

        • Zoho CRM - Analytics: How Can I Set Monday as First Day of The Week?

          Hello, In the analytics section of our Zoho CRM (not Zoho Analytics), we would like to track our SDRs' outreach activity. However, it appears that Zoho CRM treats Sunday as the first day of the week for the "This Week" and "Previous Week" filters. How

        • Flow-Level Access Permissions in Zoho Flow

          Hi Zoho Flow Team, Hope you're doing well. We would like to request a feature enhancement for Zoho Flow related to user-level access control. Use Case: As Zoho One users, we often work with multiple teams and departments. In our setup, we have several

        • Tip of the week 63- Know your contacts well with polls in Zoho Campaigns

          Communication in its true form is characterised by feedback. In email campaigns there are a few avenues via which you can achieve this. Using polls in Zoho Campaigns is one such way. With polls enabled in campaigns, your contacts can interact with your emails and help you understand them well.     There are three types of polls available to be enabled in your email campaigns:   Basic poll Rating based poll Reaction based poll     Basic poll-    Provide a question and allow the email recipients to

        • Subform data to Sheets

          I have been trying to setup a Zoho Flow automation to bring any Subform input to a Zoho Sheets but it seems impossible to post the subform entries to a Zoho Sheet. Is there any way to do it via Zoho Sheet API? https://www.zoho.com/sheet/help/api/v2/#CONTENT-Insert-row-with-JSON-data

        • The Invoice Status in Zoho Finance is misleading

          We have many overdue invoices, but when we try to filter it by Status Overdue in the Zoho Finance Module it shows it as none This is also creating a problem when I need to Create a Chart or KPI for overdue Invoices If I open the Invoice I can see the

        • Filter by technical IDs that should not be displayed

          Hello Zoho and Cumminity. I know I have already found similar requests elsewhere, but have not yet received a solution from Zoho. Therefore I would like to refresh the topic and hope that a solution can be found. I have reports in the Creator, which I

        • Problem Pasting Into Notes

          Occasionally I want to create a note by copying and pasting a few paragraphs from an article on line. When I create a new note and paste in the section the newly created note winds up with each paragraph in white text on a dark background rather than

        • Bank transaction automation

          I would like to automatically update the "Reference#" field with whatever text is in the "Description" field each time Zoho Books pulls my bank feeds. I've figured out the automation all the way up to the Field Update, where "Reference Number = ...???"

        • Payment Gateways For South Africa

          Hi, Can you please incorporate a payment gateway like Payfast etc for South African clients?

        • Custom code ass to header and footer code doesn't appear

          I am trying to insert custom code into both the header and footer of my Zoho site. I edit the site "general settings" as demonstrated in the various articles, click save, but the code does not appear on my site. Is there something special I need to do

        • Zoho Error: This Operation has been restricted. Please contact support-as@zohocorp.com for further details

          Hello There, l tried to verify my domain (florindagoreti.com.br) and its shows this error: This Operation has been restricted. Please contact support-as@zohocorp.com for further details. Screenshot Given Below -  please check what went wrong. Thanks

        • Sales IQ - Bot Builder - Forward to Operator Action Card Improvement

          Hi team, It would be a great improvement to have an additional branch out of the Forward to Operator Action Card. I would like to allow 10 seconds for an operator to pick up the chat, if they don't or if they reject the chat I would like the Bot to continue

        • Email template for customer notification on ticket reply is not being used

          I've set up an email template for notify contact up upon receiving a reply in ticket. When I send a reply to the ticket, it is not using that email template. It just sends a normal looking email. How do I make it so that the email template is being used?

        • Global Fields

          Just like Global Sets for Picklists, we would like to have global fields for any kind of field. Three things that should be saved globally: 1. The Existence of the field 2. The Name and 3. Association with a module should be set up in a respective place

        • "In Zoho CRM, during the Blueprint transition to the QC stage, I want to make the 'Packing Proof' image field mandatory."

          @Dr Saurabh Joshi @Haiku Technical Support @Ishwarya SG @Sparrow Hill President @Hugh Marshall "In Zoho CRM, during the Blueprint transition to the QC stage, I want to make the 'Packing Proof' image field mandatory."

        • how do i see a list of active End Users?

          looking for a list of who i sent invitations to be an End User?  who has signed up? 

        • Modular cannot Edit in portals

          I have a custom module in CRM. If I create in either CRM or portals, I can edit it in the CRM but I can't edit in the portal. Even if it is created in the portal it wont edit. Anyone know why? I've created a new module and it works fine but this one

        • Zoho Desk - Feature Request - Add more social channels on Community user profile

          Hi Team, While updating my profile here I noticed that it is only possible to add Facebook and Twitter social links. 1. Please consider adding at least LinkedIn and if possible, other popular channels. 2. Please consider renaming Twitter field name to

        • Hide Admin Only settings

          It would be nice if the setup menu items and settings weren't visible to non-admins. Seems like there is some confusion with users going through setup pages but not having permissions and getting an invalid permission error.

        • "In Zoho CRM, during the Blueprint transition to the image field mandatory and file upload field mandatory

          I want image and file upload field want to be mandatory during the blueprint transition In the QC done Transtion Iwant to make QC done file upload and Case QR Sticker Mandatory In Pre delivery Stage i want to make Site ready file upload field mandagtory

        • Lookups from Standard Modules to Custom Modules

          I have created an "External Contacts" Custom Module for adding Contacts who aren't directly associated with a Customer or Vendor but who are related to Orders by being a Site Contact, Job Contact, Warehouse Contact, etc for third party. How can I go about

        • Using Zobot with ChatGPT Assistant Function to Trigger API Call (e.g., Weather Info)

          I am currently integrating Zobot with an OpenAI ChatGPT Assistant using function calling. The goal is to let the Assistant trigger specific API actions based on user queries — for example, fetching the current weather when a user asks, “What’s the weather

        • Train Zia answer bot on only part of Knowledge Base?

          We are trialing Zia answer bot and hope to use it on the knowledge base to help our users find the information they are looking for. I have found how to train Zia on the entirety of our knowledge base. But is there a way to train it on only certain categories

        • Recurring Events Not Appearing in "My Events" and therefore not syncing with Google Apps

          We use the Google Sync functionality for our events, and it appears to have been working fine except: I've created a set of recurring events that I noticed were missing from my Google Apps calendar. Upon further research, it appears this is occurring

        • How to identify a ticket merge through Webhooks?

          The ticket merge functionality moves all Threads and Comments from one Ticket to another. I want to identify this action to correctly apply these changes on my application end. Currently, my application only receives a Ticket_Update notification for the

        • Native SMS Integration in Zoho Desk

          I’d like to request the addition of native SMS integration within Zoho Desk. While email and chat are still widely used, SMS has become a critical channel for fast, effective customer support, especially for urgent or time-sensitive issues. At the moment,

        • need a third party to fix email authentication dns records

          at my wit's end - zoho began giving me spf, dmarc, dkim errors two weeks ago fussed with it since and now it seems dkim is the only problem and when i added the dkim record with the key from zoho mail it still wont work tired of this, need someone who

        • Announcing Early Access to "Zoho CRM for Everyone" — A new and exciting update to Zoho CRM

          We are delighted to announce an Early Access to Zoho CRM for Everyone— a truly democratic approach to managing a CRM, gift-wrapped in an exciting and intuitive user interface. Here, multiple teams across an organization can coordinate among each other

        • Share Projects with Vendor Zoho Projects Portal

          I have a vendor/reseller of my services. They private label my services. My portal is branded. Can an individual project be "shared" or the data sync with another portal? I believe that this can be done with CRM.

        • Zoho Books - Sales Person Information

          Hi Team, On Invoices, Quotes, etc... I can include the Sales Person, but it only shows their name and not their email or phone number. It would be great to have place on invoice templates where we can manage what sales person information should be shows

        • Feature Request – Support for Stripe Direct Debit for Canadian Customers in Zoho Books

          I’d like to request support for Stripe Direct Debit as a payment option for Canadian customers within Zoho Books. Currently, while Stripe credit card payments are supported for Canadian businesses, there is no option to enable Direct Debit (ACH/EFT) through

        • Zoho Desk blank page

          1. Click Access zoho desk on https://www.zoho.com/desk/ 2. It redirects to https://desk.zoho.com/agent?action=CreatePortal and the page is blank. Edge browser Version 131.0.2903.112 (Official build) (arm64) on MacOS

        • Timentry and Support Plan Relationship

          Timentry and Support Plan Relationship A customer can buy multiple products and request different SLAs and support plans for each product. We can enter different support plans and define the credit. The scenario I want to happen; - To reduce the credits

        • Issue with ticket replies via Slack: '+' symbols replacing spaces in emails

          Hello, support team! We're experiencing an issue when replying to tickets directly through Slack. When the reply is sent to the email, spaces are being replaced by '+' symbols. This makes the message harder to read and understand. Is there any solution

        • Next Page