COQL API in Zoho CRM - Part I

COQL API in Zoho CRM - Part I

Hi everyone! Welcome back to another week of Kaizen! 

This week, we will discuss the COQL Queries in detail.

COQL (CRM Object Query Language) is a powerful query language based on SQL syntax that allows users to write their own queries and fetch records using module API names and field API names. In this post, we will discuss the operators supported by COQL in detail and also provide examples to help you understand better.  Please note that the information in the article holds true for version 4 of Zoho CRM APIs.

When should you use the Query API?

Use Query API when you want to query for a module's data and/or it's look up related data using various comparators, or for records that fall into a custom view without actually creating one. For example, if you want to query for all products in a specific price range, with a 5 star rating and sort the results by price, use the Query API. Similarly you can use Query API to query for records from cross-modules (linked via lookup field), such as filtering products based on the vendor's details. 

What types of queries are supported by COQL?

COQL supports only the SELECT query, which is used to select data from the CRM, based on the conditions specified by the clauses. 

Here is a sample query:
SELECT {field_api_names} FROM {module_api_name} WHERE {field_api_name} {comparator} {logical_operator} {value} ORDER BY {field_api_name} ASC/DESC LIMIT {limit} OFFSET {offset}

What are the clauses & aggregate functions supported by COQL?

WHERE - used to select records based on specific conditions.
FROM - specifies the module from which to fetch the records.
ORDER BY - used to sort the results in ascending or descending order.
LIMIT - used to limit the number of records returned by the query.
OFFSET - used to skip a specified number of records while retrieving the records.


{
 "select_query" : "select Last_Name, First_Name, Mobile, Final_Score from Leads where (Lead_Status = 'Not Contacted') ORDER BY Final_Score DESC LIMIT 5 OFFSET 10"
}


For example, the above query retrieves the Last_Name, First_Name, Mobile and Final_score of all Leads whose status equals 'Not Contacted'. The results will be sorted in descending order based on the Final_Score field, and only the 5 records after skipping the first 10 will be returned.

NOTE : You can also use the syntax "LIMIT offset, limit" to achieve the same result. For example :


{
 "select_query" : "select Last_Name, First_Name, Mobile, Final_Score from Leads where (Lead_Status = 'Not Contacted') ORDER BY Final_Score DESC LIMIT 5, 10"
}
​

Aggregate functions can perform calculations on a set of values and return a single value. 
SUM() - to get the sum of the values of an aggregate field in a module.
MAX() - to get the maximum value of an aggregate field.
MIN() - to get the minimum value of an aggregate field.
AVG() - to get the average value of the values of a field.
COUNT() - to get the number of records that satisfy the criteria.

Wildcard Character Support in COQL

In COQL queries, the only supported wildcard character is %. This % wildcard can be used with the like operator to achieve functionality similar to the contains, starts_with and ends_with operators. For instance, '%tech" queries for field values ending with tech, 'C%' queries for the values starting with C, and '%tech%' translates to contains 'tech'.

Supported field types and Comparators

The following table gives a gist of the field types whose data you can query for, and the comparators for each field type.
Field TypeComparators
Text and Picklist=, !=, like, not like, in, not in, is null, is not null
Lookup=, !=, in, not in, is null, is not null
Date, DateTime, Number, Currency=, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
Boolean=

Supported field types and Comparators

1) Text and Picklist Fields

Supported comparators : =, !=, like, not like, in, not in, is null, is not null. Please note that the like operator is used for starts_with, ends_with, contains, and not like operator is used for not contains. 

Sample Query 1: (=, like, in)

{
    "select_query": "SELECT First_Name, Last_Name FROM Leads WHERE (((Lead_Status = 'Pre-Qualified') and (Company like '%zylker%')) and Industry in ('Technology', 'ERP'))"
}

This SELECT query retrieves the First_Name and Last_Name of all Leads whose Lead_Status is Pre-Qualified, Company contains zylker, and Industry is either Technology or ERP. 

Sample Query 2:(not in, like, not null)

{
"select_query": "SELECT First_Name, Last_Name FROM Leads WHERE (((Lead_Status not in ('Closed-Won', 'Closed-Lost')) and (Lead_Source like '%Web%')) and (Skype_ID is not null)) LIMIT 2"
}

This query will return the first name and last name of all leads whose lead status is not Closed-Won or Closed-Lost, whose Lead Source fields contains web, and whose Skype ID field is not empty.

Sample Query 3:( !=, not like, null)

{
    "select_query": "SELECT First_Name, Last_Name, Mobile FROM Leads WHERE (((Lead_Source != 'Webinar') and (City not like '%New York%')) and (Skype_ID is null))"
}

This query retrieves the first name, last name and mobile of leads where the lead source is not a webinar, the city is not New York, and the Skype ID field is empty or null.

2. Lookup Fields

=, !=, in, not in, is null, is not null are the supported comparators for lookup fields. If you want to get the name of the lookup field in the response, you must include the field API name in the query. Otherwise, the system will return only the ID of the field.

Sample Query 1: (=, not in, !=)

{
 "select_query": "select Last_Name, First_Name, Full_Name, Account_Name, Owner from Contacts where (((Account_Name.Account_Name != 'Zylker') and (Owner = 4876876000000327001)) and Vendor_Name.Vendor_Name not in ('Skytech','SR')) LIMIT 2"
}

This query retrieves the last name, first name, full name, account name, and owner of two contacts whose account name is not Zylker, whose owner ID is 4876876000000327001, and whose vendor name does not contain Skytech or SR.
Sample Response:
{
    "data": [
        {
            "First_Name": "John",
            "Full_Name": "John Wilson  ",
            "Owner": {
                "id": "4876876000000327001"
            },
            "Last_Name": "Wilson  ",
            "Account_Name": {
                "id": "4876876000000333089"
            },
            "id": "4876876000000333182"
        },
        {
            "First_Name": "Josephine",
            "Full_Name": "Josephine Darakjy",
            "Owner": {
                "id": "4876876000000327001"
            },
            "Last_Name": "Darakjy",
            "Account_Name": {
                "id": "4876876000000333090"
            },
            "id": "4876876000000333183"
        }
    ],
    "info": {
        "count": 2,
        "more_records": true
    }
}

In this query, the id of the account is returned but not the name since we have not specified the field API name in the query. To fetch the field name, specify the field API name in the query. Refer to the following sample query to know how.

Sample Query 2:  (in, is null, is not null)

{
    "select_query": "SELECT Deal_Name, Account_Name.Account_Name, Created_Time FROM Deals WHERE (((Account_Name.Account_Name in ('Grayson','Zylker')) and (Owner is not null)) and (Contact_Name is null)) ORDER BY Created_Time DESC LIMIT 2"
}

This query retrieves the Deal Name, Account Name, and Created Time of the 2 most recently created Deals whose Account Name contains Zylker or Grayson, and do not have a Contact Name associated with them but have a Deal Owner associated with them. The results will be ordered in descending order by the Created Time.
 
Sample Response:
{
    "data": [
        {
            "Deal_Name": "Westborne Deal",
            "Created_Time": "2023-04-06T10:04:02+05:30",
            "Account_Name.Account_Name": "Grayson",
            "id": "4876876000003548001"
        },
        {
            "Deal_Name": "Eastwing Deal",
            "Created_Time": "2023-04-05T19:10:55+05:30",
            "Account_Name.Account_Name": "Grayson",
            "id": "4876876000003526011"
        }
    ],
    "info": {
        "count": 2,
        "more_records": true
    }
}

In the same query, if you want to use the Account ID instead of the name, replace ((Account_Name.Account_Name in ('Grayson','Zylker')) with ((Account_Name in (4876876000001236083, 4876876000002799001)) to include the IDs instead of the field API names and the account names.
{
    "select_query": "SELECT Deal_Name, Account_Name.Account_Name, Created_Time FROM Deals WHERE (((Account_Name in (4876876000001236083, 4876876000002799001)) and (Owner is not null)) and (Contact_Name is null)) ORDER BY Created_Time DESC LIMIT 2"
}

3. Date, DateTime, Number, Currency Fields

=, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null are the supported comparators for these fields.

Sample Query 1: (between, <, >)

{

    "select_query": "SELECT Deal_Name, Amount, Stage, Probability FROM Deals WHERE (((Closing_Date between '2023-01-01' and '2023-03-31') and (Probability < 99)) and (Amount > 10000))"

}

This query retrieves the deal name, amount, stage, and probability of all deals whose closing date is between January 1, 2023 and March 31, 2023, and whose probability is less than 99 and amount is greater than 10000.

Sample Response:
{
    "data": [
        {
            "Deal_Name": "Chapman Deal",
            "Amount": 2500000,
            "Probability": 97,
            "Stage": "Closed Won",
            "id": "4876876000003550011"
        }
    ],
    "info": {
        "count": 1,
        "more_records": false
    }
}

Sample Query 2: (<=, !=, >=)

{
    "select_query": "SELECT Product_Name, Qty_in_Stock, Vendor_Name, Cost_Price FROM Products WHERE (((Sales_End_Date <= '2023-04-30') and (Qty_in_Stock != 0)) and (Cost_Price >= 500))"
}

This query retrieves the product name, quantity in stock, vendor name, and cost price for all products whose sales end date is on or before April 30, 2023, whose quantity in stock is not zero, and whose cost price is greater than or equal to 500. Since Vendor_Name is a lookup field, only the ID will be returned in the response.
Sample Response
{
    "data": [
        {
            "Cost_Price": 2000,
            "Vendor_Name": {
                "id": "4876876000001039017"
            },
            "Product_Name": "Sigma",
            "Qty_in_Stock": 30,
            "id": "4876876000001036109"
        }
    ],
    "info": {
        "count": 1,
        "more_records": false
    }
}

Sample Query 3: (not between, is not, >)

{
    "select_query": "SELECT Last_Name, First_Name, Referred_By.Full_Name FROM Leads WHERE (((Final_Score not between 10 and 20) and (Annual_Revenue is not null)) and (No_of_Employees > 200)) LIMIT 1"
}

This COQL query selects the last name, first name, and the full name of the lead's referred by field, for one lead whose final score is not between 10 and 20, annual revenue is not null and whose number of employees is greater than 200. 
Sample Response
{
    "data": [
        {
            "First_Name": "Chau",
            "Last_Name": "Kitzman",
            "id": "4876876000000333403",
            "Referred_By.Full_Name": "Simmons Truhlar"
        }
    ],
    "info": {
        "count": 1,
        "more_records": true
    }
}

Sample Query 4: (>, not in, =, is null)

{
   "select_query":"SELECT PO_Number, PO_Date, Status, Discount FROM Purchase_Orders WHERE (((PO_Date = '2023-04-06') and (Due_Date not in ('2023-04-10','2023-04-11', '2023-04-12'))) or ((Discount > 10) and (Requisition_No is null)))"
}

This query selects the PO_Number, PO_Date, Status, and Discount from the Purchase_Orders module where the PO_Date is equal to '2023-04-06' and Due_Date is not any of '2023-04-10', '2023-04-11', or '2023-04-12'; OR Discount is greater than 10 and Requisition_No is null. In this query, we have used both AND and OR operators to combine the clauses.
Sample Response
{
    "data": [
        {
            "Status": "Created",
            "PO_Date": "2022-05-10",
            "Discount": 9990,
            "PO_Number": "PO-JL-3876",
            "id": "4876876000001125176"
        },
        {
            "Status": "Created",
            "PO_Date": "2023-04-06",
            "Discount": 370.37,
            "PO_Number": "PO-DA-1932",
            "id": "4876876000003561019"
        }
    ],
    "info": {
        "count": 2,
        "more_records": false
    }
}

We hope you found this post useful and that it has given you a better understanding of COQL queries. In our next post, we will discuss the rest of the field types, aggregate functions with more examples, and provide more queries to help you get started.

If you have any questions or feedback, please let us know in the comments below, or write to us at support@zohocrm.com. We would love to hear from you! 

Additionally, if you have any questions about the COQL API or how to construct a query, kindly let us know in the comments.

Additional Reading:





        • Recent Topics

        • Confirmation prompt before a custom button action is triggered

          Have you ever created a custom button and just hoped that you/your users are prompted first to confirm the action? Well, Zoho knows this concept. For example, in blueprint, whenever we want to advance to the next state by clicking the transition, it is

        • Frontal interview scheduling - room availability in office using Google Workspace?

          Hi, We're using Zoho Recruit as our ATS and Google Workspace as our email, calendar and resources management. We want to use the interview feature to schedule an in-person (frontal) interview with the applicants. How can we sync the room resources availability

        • Add and Remove Agents from Departments and Groups in Zoho One

          Hi Zoho Flow Team, We hope you're doing well. Currently, Zoho Flow provides an action to add an agent to a group in zoho one, but there is no action to remove an agent from a group or a department. Another action that we find missing is the option to

        • Introducing Hiring Pipeline for Vendor Portal

          Keeping vendors informed about candidate progress is often challenging, leading to communication gaps and repeated follow-ups. To address this issue, we've released an update to the Vendor Portal feature that lets you choose to display candidates' hiring

        • Address Grabber function for Zoho

          I converted from ACT to Zoho. With ACT, I used an add-on called AddressGrabber to scrape the contact information from leads that I buy and contact information contained on emails and websites and directly add it as a new lead or contact. Does anyone know

        • Integrate zoom with zoho bookings please; or add optional times in zoho meetings

          Just like events - these online meetings like zoom need to be integrated with zoho bookings, and there needs to be option for customer to book a time slot. It should not be dictated by CRM user.

        • Add Owner to deluge-created module record note

          Is it possible to include the "owner" aka "creator", of a Note when creating it via delulge? This sets "superadmin" as the Note creator. I need to override it. notemap = Map(); notemap.put("Parent_Id",program_contact_id); notemap.put("Note_Content",program_contact_data.get('Note'));

        • Unique and Random IDs in Zoho Forms: Organize and Secure Your Data Efficiently

          When it comes to form submissions, organizing and identifying entries effectively is crucial. Zoho Forms offers two versatile ID generation options for submissions: Unique ID and Random ID. Each serves distinct purposes, providing flexibility to meet

        • Sort By Date - Deluge

          I have the following code, which normally works to sort calls by created time. Every once in a while, it doesn't work and something sneaks through in the wrong order and I can't figure out why. calls = zoho.crm.searchRecords("Calls","(Owner:equals:" +

        • Iteration through a list - Coming up against a "Failure to update function" error

          Hi there! I've been attempting to get a deluge script working and am running into an error that I have been unable to resolve. The error I am getting is Failed to update function Error at line :18. Improper Statement. Error might be due to missing ';'

        • Can you modify "Last Activity Time" in deluge? If so what's the field name?

          I need to perform some bulk modifications on records in the Leads module, but I need to avoid changing the "last activity time" or "date modified" because I am using those fields to filter and sort leads for follow-up action. I cannot find an answer anywhere

        • How do I define a weekend

          I noticed the default for weekends does not seem to include Saturdays. How can i define weekends to include both Saturdays and Sundays? Thank you.

        • 【Zoho CRM】ポータル機能のアップデート

          ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 今回は「Zoho CRM アップデート情報」の中からポータル機能のアップデートをご紹介します。 今回の機能アップデートにより、CRMのポータルへのログインがより簡単にできるようになりました。 【目次】 SAMLベースのシングルサインオンについて ポータルへのアクセスリンク送付について 今回のアップデートにより、アイデンティティプロバイダー（IdP）を利用している組織において、SAMLベースのSSO（シングルサインオン）を有効化できるようになりました！

        • Getting error during inserting a record in form of zoho people using zoho api

          import requests import json # Set your access token and Zoho People API base URL access_token = '1000.XXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXXXXXXX' api_base_url = 'https://people.zoho.in/people/api/' # Set the form name and data to be inserted form_link_name

        • UI Arabic

          can i change the member portal UI to arabic in zoho community?

        • Resume template to include profile photo

          Hi, We would love the Resume Template to be able to include their profile photo. How can this be done? Miriam

        • Marking a form as 'done'?

          Hi! I've got a form that staff fill in when moving stock from location to location. I see the entries they've sent across and I input them into my stock control system. Is there a way to mark a form as 'done'? So that I know which entries I've input,

        • Zoho CRM - best way to search an account and assign to a deal

          Hi Everyone I am looking for some advice. I want to find the best way to complete the below steps. We have a deal and once it reaches a certain stage we need to allocate a supplier / vendor to this deal along with the salesperson. I want to add (ideally

        • Zoho Rating

          When I close a ticket, the zoho system automatically sends an email to the customer for them to leave a rating. When they leave a rating, the ticket re-opens and I have to close it again. When I close it again, the zoho system sends the customer an email

        • Zoho GC Flow is not showing in IM Channels

          I have added my social IM channels in zoho desk. Created a GC Flow to automate conversations. But Guided conversations are not showing in any platforms I have chosen; WhatsApp Instagram Messenger Web (Business Messaging) In the flow I mentioned these

        • Sharing Knowledge Base articles across multiple departments

          It would be useful to share some Knowledge Base articles across multiple departments where they are applicable, rather than having to go into other departments to find the article you're looking for. For example. Our reception uses the 'Admin' desk whereas our IT guys use the 'Support' desk, however both divisions would find KB articles about our company intranet useful. Reception does not have access to the support desk, so cannot see articles created in the Support KB. Perhaps you could install

        • Contacts marked as Spam are shown as Contacts in tickets.

          Hi Zoho, If a ticket is marked manually as Spam you get an option to set the contact as Spam as well. It would be great if there was another option to delete this Contact. This would be based on the understanding that it wouldn't be marked automatically

        • Is possible to use ${webhookTrigger.payload.street==null?"No street":${webhookTrigger.payload.street}} for to detect inline a null parameter

          Hi Team I need to know if it's possible to evaluate inline the following parameter, with the objetive to detect a null value ? I would like to use ${webhookTrigger.payload.street==null?"No street":${webhookTrigger.payload.street}} Regards, Pablo

        • Real Estate CRM

          How can I tailor my CRM for real estate? I had seen an image where the CRM included property tabs.

        • Issue with Bulk Edit Triggering Function Multiple Times in Zoho Report

          In our Zoho report, we have observed an issue where executing a function during a bulk edit operation runs the function multiple times—once for each selected report entry. This behavior is causing errors due to overlapping or redundant executions. Our

        • Set recurring tasks in Zoho Support?

          Hello,   We use the task function in Zoho Support to set reminders for "due dates" of important events, such as lease expirations, etc. Is it possible to set some of these as recurring yearly? As of now, we have to reset every task manually after one year. Is there a way to have it reset automatically?   Additionally, is there a way to import a list of tasks and their dates into Zoho Calendar? I have not been able to do it from Zoho Support to Calendar. I tried exporting tasks from Zoho Support,

        • Help - How Can I Enter a Hourly Rate (Global Cost) for our Team for Profitability Reporting?

          Hi everyone, I'm hoping someone can help as I am at a loss and am quite shocked (if true) at the lack of functionality in Zoho Books. We run a company in which we do hourly jobs for clients and we bill based on the hours of work completed. Projects are

        • Schedule a regular backup

          In CRM I have a regular backup setup. I cannot find an option to backup Desk? I would like to take a backup before I test syncing products between CMR and Desk.

        • Limit who can submit a support ticket to your site?

          Does anyone have a use case for needing to limit who can submit tickets via your help portal? Some of our customers want to have end-users view our knowledge base articles and see tickets their IT groups have submitted but they do not want end-users to

        • Is there a way to request a password?

          We add customers info into the vaults and I wanted to see if we could do some sort of "file request" like how dropbox offers with files. It would be awesome if a customer could go to a link and input a "title, username, password, url" all securely and it then shows up in our team vault or something. Not sure if that is safe, but it's the best I can think of to be semi scalable and obviously better than sending emails. I am open to another idea, just thought this would be a great feature.  Thanks,

        • Allow us to disable the Reopen Ticket button after a ticket is closed

          Disabling the Reopen Ticket will allow us to have more control over the ticket's flow. According to support, this is currently not possible. Please add this to let us, the customers, mold the ticketing system into something that we can use for our business

        • How to Enforce Mandatory Fields (Category/Sub-category) Before Closing a Ticket?

          Hi, I'm currently using Zoho Desk and encountering an issue where agents are able to close tickets without filling out mandatory fields, specifically Category and Sub-category. I’ve already set them both as a mandatory field, but it can still be bypassed

        • Admin Control for Default Email Templates in Zoho Desk

          Hi Zoho Desk Team, We would like to request a feature enhancement related to default email templates. Currently, agents can select and set their own default email templates when replying to tickets. However, we believe this setting should be managed centrally

        • Lock out of account after password update

          This is a bit of a catch 22 situation. I updated my account password using password generator in ZohoValut. Now I am locked out of everything, as I cannot get into OneAuth for 2FA, as the password is randomly generated, without getting into ZohoValut,

        • Guidance on Making Zoho Desk Connections Available for All Data Centers

          Hi Team, I’m currently developing an application using Zoho Desk connections to manage OAuth for my third-party products. Could you please advise on the steps required to make it available across all data centers? Looking forward to your thoughts on

        • Multibrand Help Center - Share knowledge base catgories between multiple departments

          Hello, I would like to know if it is possible to share categories between multiple departments when the multi brand feature is enabled. So that then one portal exists per department, but certain categories are visible in multiple portals. After all, we

        • Unable to upload document error on zoho sign

          i am creating a document using laravel php and here is my code and i get this reponse {"code":2005,"message":"Unable to upload the document","status":"failure"} $path = storage_path($file); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, 'https://sign.zoho.com/api/v1/requests');

        • Cloud to cloud folder migration from Sharepoint to Workdrive

          I am aware of OneDrive migration: https://help.zoho.com/portal/en/kb/workdrive/migrations/microsoft/articles/migrate-from-onedrive-to-zoho-workdrive#Whats_migrated would this cover a Sharepoint migration meaning I can move a whole Sharepoint (team) folder

        • Zoho Sign / Prefill By You - Editable by Them!

          Zoho Sign seems to have two field options available - an empty field for signer(s) to complete or a field that has been prefilled by you, that becomes read only once sent.  What I would like is an option on the pre-filled by you fields, to leave them

        • Kiosk Studio wrap-up | How our community used kiosks in 2024

          Hello, everyone! Happy new year! The end of 2024 has been busy, and 2025 promises to be bigger and better. As we ring in the new year, let's rewind and look at Kiosk Studio, our no-code customization tool. The past 300 days have seen the CRM community

        • Next Page