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
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
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! CommandsKaizen #165 : How to call Zoho CRM APIs using Client Script
Welcome back to another exciting Client Script post! In this post, we will discuss one of the most frequently asked questions: How do you call Zoho CRM APIs from Client Scripts? In this kaizen post, 1. Ways to make calls to Zoho CRM APIs using ClientKaizen#162 : Add Tags and Open Pre-filled Email Drafts via Client Scripts
Hello everyone! Welcome to another informative Kaizen post. In this post, let us see how to accomplish the following using Client Script. 1. How to auto-tag a record based on field update? 2. How to Open a pre-filled email draft This post will provideExtension Pointers - JS SDK series #4: Managing data from a widget using ZOHO.CRM.HTTP
Handling and managing the data between two applications is a major factor for an efficient business. There are a variety of ways to handle data between Zoho CRM and other third-party applications. You can use deluge CRM tasks, create connectors, use APIKaizen #152 - Client Script Support for the new Canvas Record Forms
Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved
New to Zoho TeamInbox?
Zoho TeamInbox Resources
Zoho DataPrep Resources
Zoho CRM Plus Resources
Zoho Books Resources
Zoho Subscriptions Resources
Zoho Projects Resources
Zoho Sprints Resources
Qntrl Resources
Zoho Creator Resources
Zoho Campaigns 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
Customer Happiness not clickable when using API
Is there a way to automatically add the Customer Feedback links when generating email drafts via the API? Currently, the feedback links are only added when generating an email draft using the UI. I tried using the endpoint described in https://desk.zoho.com/DeskAPIDocument#CustomerFeedback#CustomerFeedback_GetthecustomerfeedbackplaceholderlinkSend To Zoho Sign not Showing
The button send to Zoho sign is not showing on my Zoho CRM . Is there additional steps I need to take after installing Zoho Sign to CRM ?How to Get An Image's URL once it's uploaded to library?
I manage to find URLs to the images I uploaded to my library, but after a day, it seems the links stop working like its only temporary. Where can I find the ACTUAL solid URL for my images that I upload to my Library so I can use them for my custom template / HTML coded template? Thanks, Mac【Zoho CRM】インポート機能のアップデート：既存データへのタグ追加が可能に！
ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 今回は「Zoho CRM アップデート情報」の中のインポート機能のアップデートをご紹介します。 Zoho CRMのタグは、データを効率的に分類、認識するためのラベルです。 タグ付けは次の3つの方法で行えます： 個別タグ付け：少数のデータを手動でタグ付け 自動化：特定のタイミングで繰り返しタグ付け 一括更新：インポート機能でタグを追加または更新 今回のアップデートでは、インポート時に既存のタグを残したまま、新しいタグの追加、既存タグを置き換えできるようになりました。Link to Desk tickets
Hello, We are using Analytics to analyze data in Desk. Is there a way to embed a link to a ticket in reports? We'd love to be able to see the drill down data, and click a value in a result row that would launch the Desk Ticket in another window/tab. Thanks in advance for any ideas!Bluerprints: How to connect the created record back?
I've a blueprint which creates another record as part of an 'After' transition. But the two records don't seem to be linked together. If it's not automatic - how do I get the created record ID to link it to the original record? Thanks!Populate a Related List Item based on a Stage
I would like to know if I can populate a CLOSED DEAL section in a contact that populates only when a Deal (something in the Deal Module) is listed as Closed - Won. I'd like another section that is just called deals, which shows me all other deals thatBeing able to draw inside a module ?
I was wondering if anyone know of a solution for this request. We would like to be able to draw directly from one module in the CRM and have it attached to that record. Here is an example. Paul would go to the customer once he as done the measuring, he2 serial numbers for 1 item (Mac address and Serial number)
There is a way to track 2 serial number type for 1 Item. Ex: Some electronic devices have a MAC address and a serial number. I need to track those 2 numbersHolidays
Hi; For defining Holidays, you need to add logic to handle the year as well as the month & day. We need to be able to enter Holidays for the next year. I need to add a holiday for January 2, 2017, but I can't until January 1st, which is a Sunday and weDelete a department or category
How do I delete a Department? Also, how do I delete a Category? This is pretty basic stuff here and it's impossible to find.Remove or hide default views
I'm looking to only have the views pertinent to my organization. Is there a way to show only my custom views (or separate them to a different area or something)? If not, this should be a feature as switching from Zendesk we had this option...Analytics Module: Can you move items from one dashboard to another?
Is there a way to move items from one dashboard to another? I want to rearrange my dashboard now that I know what i'm doing but i don't want to remake my various widgets? Edit: Hey Zoho, This would be a good feature: to be able to move/copy widgets toCopy Widget to another Dashboard
I can see the option to clone a widget to the same dashboard but is it possible to copy it to another dashboard?Is there a way to print the dashboard?
I would like the capability of printing the dashboard - is that possible?Custom Deal Name in Lead Conversion Mapping
I know there are ways to change the name of a Deal after conversion using a custom function, so no need to repost that information. I would like to see the CRM Improved with Deal Name Customisation and I think the Lead Conversion Mapping page would beBuild custom AI solutions with Catalyst’s QuickML capabilities in CRM
Hello everyone, We’re thrilled to announce an improvement for our Zoho CRM Enterprise users: the ability to create custom AI solutions using Catalyst’s QuickML directly from Zoho CRM. As you may already know, Zia, Zoho CRM’s AI-powered assistant, offersIntroducing Record Summary: smarter insights at your fingertips
Hello everyone, Building on the recent launch of Zoho's in-house Zia Large Language Model (Zia LLM)—a major milestone in Zoho CRM’s AI capabilities—we’re excited to introduce the Record Summary feature. This powerful addition makes use of Zia LLM to simplifySuppress "spreadsheet will not be saved" message on published sheet
I have published a sheet and have one column on that sheet that the user can edit (a dropdown picklist where the user can select the status for each line). Is there a way to suppress the Zoho Sheet message "Any changes made to this published spreadsheetMissing "Email Authentication" tab
Backstage is alerting users about "Unauthenticated Domains" with a large prompt in the backend. It adds a link to learn more. On this tutorial page, it shows where to find the "Email Authentication" tab in this screenshot. However, in our Backstage, thatShow item Cost value on Item screen
The Item screen shows Accounting Stock and Physical Stock. It would be very helpful if value information could be displayed here as well, for instance Cost Price. Currently, to find the Cost Price (as used for inventory valuations) from inside the itemZoho Analytics to Zoho Sheets - automatic update?
Hi all, If I create a zoho sheet from an Analytics Report or Analytics Data, is there a way for the zoho sheet to automatically update as the Report / Data in analytics updates?Integration with Moodle
Greetings, I hope find all doing well and safe. I've recently returned to using Zoho Flow after a break and was hoping to connect my WooCommerce store with Moodle, the world's most widely used learning management system. My goal was to automatically enrollHow to Record Loan with interest
I have received loans from friend he give me like 2 loans so far one is one year repayment and one short, how to properly record his payment, and repayment and give him statement for each loan he give meTask status - completed - other options
I have a dumb question I know i can make custom statuses for the tasks - but is there anyway to make additional "completed" statuses like for instance if i have a task "call back customer" and i leave a vm for them to call back marking it "completed -Task module and related-to field
In modules other than the Task Module I can add several lookup fields to provide a variety of relationships. In the Task module lookup fields are not available. There is only one "related to" field which I want to use for Company. But I want to relateAdd Lookup Field in Tasks Module
Hello, I have a need to add a Lookup field in addition to the ones that are already there in the Tasks module. I've seen this thread and so understand that the reason lookup fields may not be part of it is that there are already links to the tables (https://help.zoho.com/portal/en/community/topic/custom-fields-on-task-module).migrating from Zoho Invoices (CRM) to Zoho Books
Good day, I was wondering if there was a easy way to migrate all the quotes and invoices from Zoho Invoices CRM to Zoho Books. We plan to move to using Zoho Books in a few weeks and would like to have all the quotes and invoices from the past 3 yearsZoho MA and Custom Module
I am trying to create a sync between Markting Automation and Zoho CRM. I am mapping a custom module from the CRM. The custom module has email field mobile phone field However I cannot finish the integration since the system keeps asking me for email orWhen is partial reimbursement going to be launched?
Hi there. I saw somewhere that the partial reimbursement feature is in the work. What is the update and ETA of that? Our clients and prospects have been asking us and we agree that that is an important feature to have.Year-End Wrap: Declutter Your Inbox Using Email Filters
Ping!—an email drops in. And another. And another! It's finally that time of the year when your inbox will be bursting with messages from team members, clients, and marketing agents, leaving you feeling overwhelmed and distracted. Sounds familiar? NowUnified Notes View For Seamless Collaboration
To facilitate better coordination among different departments and team members, the notes added to a record can now be accessed in all its associated records. With this, team members, from customer service representatives to field technicians, can easilyQ4 Europe In-person Zoho User Group Meetup: Streamlining Your Business Processes & Introduction to Zoho CRM for Everyone
Hello Zoho Community, We are excited to announce our upcoming Zoho User Group meetup in Europe! This session is designed to help you streamline your business processes using Zoho CRM, with a special focus on enhancing customer interactions and leveragingFormula fields - Request for dynamic recalculation / proper implementation
Hi Guys, I have a big problem with Zoho formula fields. They don't recalculate each time the record is viewed - only when a record is edited. Formula fields should be updated dynamically each time a record is retrieved. As an example: I have a formulaItems attribute questions
Many of my items have attributes, such as size and color. How can I add new fields to the "New Items" screen to capture that in my Purchase Orders, Items, and Sales Order pages? I only see these attribute fields when adding an Item Group. Also, on theOrganize and Track Phases with Phase Custom Views
Phase Custom Views let you filter and display phases based on specific criteria. This helps you focus on what’s most relevant for you and your team. Filter phases using criteria such as budget, status, and more. Share views with specific users or teamsRecord Asset Received as Payment
How exactly would you account for this in books? For example, I receive a mini computer for a review and I get to keep it after the video is published. Would debit my normal asset account (e.g. Computers) and credit an income account (e.g. Other Income).Invoice Line Item Report
Is it possible to run an 'Invoice Line Item Report'? The 'Invoice Details Report' shows one row per invoice. I would like one row per Invoice Line Item.Transform Your Customer Support with AI-Powered Chatbots in Zoho SalesIQ
Ever wondered how some companies seem to have superhuman customer support? Let's uncover their secret! In the digital age, customer expectations are skyrocketing. Did you know that according to McKinsey, 75% of consumers expect a response within fiveProgressive Invoicing
Progressing invoicing is needed for many industries. It would be great to see it implemented into Zoho Books as well. Set up and send progress invoices in QuickBooks Desktop (intuit.com)Next Page