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 Type | Comparators |
| 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:
Access your files securely from anywhere
New to Zoho Recruit?
Zoho Developer Community
New to Zoho LandingPage?
Zoho LandingPage Resources
New to Zoho Survey?
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Bigin?
Topic Participants
Anu Abraham
DataWarehouse
dkvagency
Jeganprabhu S
Anamika Prasanth
Sticky Posts
Kaizen #197: Frequently Asked Questions on GraphQL APIs
🎊 Nearing 200th Kaizen Post – We want to hear from you! 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 #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.Celebrating 200 posts of Kaizen! Share your ideas for the milestone post
Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQsKaizen #193: Creating different fields in Zoho CRM through API
🎊 Nearing 200th Kaizen Post – We want to hear from you! 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.Client Script | Update - Introducing Commands in Client Script!
Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands
New to Zoho TeamInbox?
Zoho TeamInbox Resources
Zoho CRM Plus Resources
Zoho Books Resources
Zoho Subscriptions Resources
Zoho Projects Resources
Zoho Sprints Resources
Qntrl Resources
Zoho Creator Resources
Zoho CRM Resources
Design. Discuss. Deliver.
Zoho Show Resources
Get Started. Write Away!
Writer is a powerful online word processor, designed for collaborative work.
Zoho CRM コンテンツ
-
オンラインヘルプ
-
Webセミナー
-
機能活用動画
-
よくある質問
-
Ebook
-
-
Zoho Campaigns
- Zoho サービスのWebセミナー
その他のサービス コンテンツ
Nederlandse Hulpbronnen
ご検討中の方
Recent Topics
Unified customer portal login
As I'm a Zoho One subscriber I can provide my customers with portal access to many of the Zoho apps. However, the customer must have a separate login for each app, which may be difficult for them to manage and frustrating as all they understand is thatWhatsApp Channels in Zoho Campaigns
Now that Meta has opened WhatsApp Channels globally, will you add it to Zoho Campaigns? It's another top channel for marketing communications as email and SMS. Thanks.Is it possible to customize ZC Themes?
I understand you can choose a layout and customize Brand Color, App Header, Menu, and Sub-Menu components, but can you override some of the default theme settings with CSS or a config file? For example, - Table highlight color - Listview auto filter highlighterror : Object code : 6500
b3 = map(); b3.put("name", "Test Project Name"); updateprojects2 = invokeurl [ url :"https://projectsapi.zoho.eu/restapi/portal/era0130/projects/169495000000928007/" type :PUT parameters: b3 connection:"in2" ]; info b3 ; info updateprojects2; ------------Tracking KPIs, Goals etc in People
How are Zoho People users tracking employee targets in People? For example, my marketing assistant has a target of "Collect 10 new customer testimonials every month". I want to record attainment for this target on a monthly basis, then add it to theirText snippet
There is a nice feature in Zoho Desk called Text Snippet. It allows you to insert a bit of text anywhere in a reply that you are typing. That would be nice to have that option in Zoho CRM as well when we compose an email. Moderation Update: We agree thatIs it possible to create Custom function-based Lookup field in Zoho CRM
Is it possible to create a custom function-based lookup field in Zoho CRM? If so, how? Use case: Need to fetch users from Zoho Projects into a dropdown field in Zoho CRM.Zoho Projects app update: Voice notes for Tasks and Bugs module
Hello everyone! In the latest version(v3.9.37) of the Zoho Projects Android app update, we have introduced voice notes for the Tasks and Bugs module. The voice notes can be added as an attachment or can be transcribed into text. Recording and attachingCreate a list of customers who participated in specific Zoho Backstage events and send them an email via Zoho CRM
How to create a list of customers who participated in specific Zoho Backstage events and send them an email via Zoho CRM? I was able to do a view in CRM based on customer that registered to an event, but I don't seems to be able to include the filterHow can I see content of system generated mails from zBooks?
System generated mails for offers or invices appear in the mail tab of the designated customer. How can I view the content? It also doesn't appear in zMail sent folder.How to conditionally embed an own internal widget with parameters in an html snippet?
Hello everyone, I'm trying to create a dynamic view in a page using an HTML snippet. The goal is to display different content based on a URL parameter (input.step). I have successfully managed to conditionally display different forms using the followingZadarma + Zoho CRM Integration – Missed Calls Saved as Contacts Instead of Leads
Hello everyone, I’m looking for input from anyone with experience using the Zadarma + Zoho CRM integration. Currently, I’m seeing that missed calls are automatically being created as Contacts instead of Leads. From a CRM perspective, this doesn’t makeCustom Button Disappearing in mobile view | Zoho CRM Canvas
I'm working in Zoho CRM Canvas to create a custom view for our sales team. One of the features I'm adding is a custom button that opens the leads address in another tab. I've had no issue with this in the desktop view, but in the mobile view the buttonSearch Records returning different values than actually present
Hey! I have this following line in my deluge script: accountSearch = zoho.crm.searchRecords("Accounts","(RS_Enroll_ID:equals:" + rsid + ")",1,200,{"cvid":864868001088693817}); info "Account search size: " + accountSearch.size(); listOfAccounts = zoho.crm.searchRecords("Accounts","(RS_Enroll_ID:equals:"Windows Desktop App - request to add minimization/startup options
Support Team, Can you submit the following request to your development team? Here is what would be optimal in my opinion from UX perspective: 1) In the "Application Menu", add a menu item to Exit the app, as well as an alt-key shortcut for these menusFunction 56: Automatically enable the option for customers to pay via bank account
Hello everyone and welcome back to our series! One of the key features of Zoho Books is its integration with multiple payment gateways, allowing you to receive online payments for your invoices. This ensures faster payments, automates payment trackingAttach Files to Your Notecards and share them on the go!
Hey everyone! We’re excited to share a feature many of you have been asking for — you can now attach files directly to your text notecards and share with ease! 🙌 This update was built with your feedback in mind, especially for those who wanted a simpleCan i connect 2 instagram accounts to 1 brand?
Can i connect 2 instagram accounts to 1 brand? Or Do i need to create 2 brands for that? also under what subscription package will this apply?Workdrive on Android - Gallery Photo Backups
Hello, Is there any way of backing up the photos on my android phone directly to a specific folder on Workdrive? Assuming i have the workdrive app installed on the phone in question. EmmaIntegración Books para cumplir la ley Crea y Crece y Ley Antifraude (VeriFactu)
Hola: En principio, en julio de 2025, entra en vigor la ley Crea y Crece y Ley Antifraude (VeriFactu). ¿Sabéis si Zoho va a cumplir con la ley para cumplir con la facturación electrónica conectada a Hacienda? GraciasYouTube Live #1: AI-powered agreement management with Zia and Zoho Sign
Hi there! We're excited to announce Zoho Sign’s first YouTube live series, where you can catch the latest updates and interact with our Zoho Sign experts, pose questions, and discover lesser-known features. We're starting off by riding the AI wave inMass Mail Statistics - Number of unsent emails
How do I find out which emails were not sent?How to add a % Growth column for year-over-year comparison (2024 vs 2025)
Hello, I am trying to build a monthly revenue comparison between 2024 and 2025 in Zoho CRM Analytics. My current setup is: Module: Deals (Affaires) Filter: Stage = Closed Won Date field: Closing Date Grouping: By Month Metrics: Sum of Amount for 2024,How to searchByCriteria records that are under approval?
I need to search for both approved and pending approval records Is that possible with this method? Or I need to a different method? var priceReqID = $Page.record_id; log(priceReqID); var records = ZDK.Apps.CRM.Price_List_Item.searchByCriteria("Price_Request:equals:"Power of Automation::Streamline log hours to work hours upon task completion.
Hello Everyone, A Custom Function is a user-written set of code to achieve a specific requirement. Set the required conditions needed as to when to trigger using the Workflow rules (be it Tasks / Project) and associate the custom function to it. Requirement:-How to add Simple Analytics to Zoho Pages?
I have a website with Zoho Pages, how do I add Simple Analytics on it? They seem to have code they need to be embedded https://docs.simpleanalytics.com/scriptProduct details removed during update from other system
We maintain our product details in an other system. These details are synchronized with Zoho at the end of each day, through an API. This has worked perfectly sofar. But last Monday, all product codes and some other product data have been wiped duringEnd Date in Zoho Bookings
When I give my appointments a 30 minutes time I would expect the software not to even show the End Time. But it actually makes the user pick an End Time. Did I just miss a setting?I hate the new user UI with the bar on the left
How can I reverse this?Cant seem to delete an email account
Hello, I have researching for 4 days how to delete an email account and I am absolutely without a clue. The email account I am trying to delete is support<AT>fyshoes<dot>com. It's the first email account I made and it (is???) was associated with the super user (me). I have since changed it to adming<AT>fychoes<dot>com and I see the support email in my list but I just cant seem to get rid of it. Ultimately I want to associate that email account with another user that I want to add. This is reallyCommerce Order as Invoice instead of Sales Order?
I need a purchase made on my Commerce Site to result in an Invoice for services instead of a Sales Order that will be pushed to Books. My customers don't pay until I after I add some details to their transaction. Can I change the settings to make thisSync desktop folders instantly with WorkDrive TrueSync (Beta)
Keeping your important files backed up and accessible has never been easier! With WorkDrive desktop app (TrueSync), you can now automatically sync specific desktop folders to WorkDrive Web, ensuring seamless, real-time updates across devices. Important:Script that deletes a record?
We're using WP Plugin "Integration for WooCommerce and Zoho Pro", and have created a couple of Feeds to send data to Zoho. We are trying to create Contact records, but only based upon condition. Tried to make it with small Deluge function and Workflow,Introducing Profile Summary: Faster Candidate Insights with Zia
We’re excited to launch Profile Summary, a powerful new feature in Zoho Recruit that transforms how you review candidate profiles. What used to take minutes of resume scanning can now be assessed in seconds—thanks to Zia. A Quick Example Say you’re hiringImport data into Multi-Select lookup field from CSV/Excel
How to import data into a multi-select lookup field from the CSV/Excel Sheet? Let's say I have an Accounts multi-select lookup field in the Deals module and I want to import the Deals with Accounts field. Steps:- 1. Create/edit a multi-select lookup fieldAuto Capitalize First Letter of Words
Hi I am completely new to ZOHO and am trying to build a database. How can i make it when a address is entered into a form field like this: main st it automatically changes is to show: Main St Thank YouA formula that capitalises the first letter of each word
Hi all, is there a zoho formula that can capitalise the first letter of each word in a string? INITCAP only capitalises the first letter of the first word.Add Analytics function for Title case (capitalising each word in a string)
At present, you can only capitalise each word in a string in Analytics during data import. It would be really useful to be able to do this with a formula column, but there is no Title Case function.Office 365 and CRM mail integration: permission required
Has anyone run into this weird problem? My email server is Office 365. When I try to configure Zoho CRM to use this server, a Microsoft popup window opens requesting user and password. After entering that, I get a message in the Microsoft window sayingUpdating Subform Record from other Form
Just wanted to ask how to properly approach this. I have 2 forms and would like to trigger an auto update on the subform once record submitted. block below only updates 1 row for each recordRow in input.AV_System { AssetRecord = Site_Asset_Services[SOR_NoNext Page