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

    • Printing on 80mm bluetooth Pos Printer

      Hello. I am trying to print receipts and invoices using my 80mm bluetooth connectivity Pos printer. I have configured the Templates to Retail so that it matches the paper width of the Pos printer. However, when I click Print in zoho, first it opens the

    • Trying to integrate gmail but google keeps blocking Zoho access for integration??

      hi i am trying to integrate a gmail account so can track/access business emails this way. I have followed the instructions but after selecting my email account it gets re-routed to this message (screengrab below) Can anyone advise a way around this or

    • Which attribute in Zoho books invoice api represent branch attached to the invoice?

      Hi Zoho Team, We have done the integration with Zoho Books API. While fetching data from Invoice API we want to get branch value attached to the invoice. We could not figure out which field in "Get an Invoice" api represents branch value attribute. Thanks

    • How to Billed from two different GST Numbers

      How to Billed from two different GST Numbers. Suppose ABC & Co had GST registration in Delhi and Haryana and Zoho account is created with Delhi GST Registration number. Now i also want to issue invoice from Haryana GST Registration number. How can i proceed ?

    • How to hide Predefined views

      Hi, I would like to know how to hide: Predefined views and Recent views or some records from this list. If I'm using it form iPad I have to scroll to see User created views. Or maybe it's possibility to move User created views on the top. All the best,

    • Is it possible to trigger the review process when a record is edited?

      Hello, I need to trigger a review process whenever a field is updated to a specific value. This field is empty when the record is created and is only filled later. I know the approval process exists, but that's not what I'm looking for in this case. What

    • How to Customize Task Creation to Send a Custom Alert Using JavaScript in Zoho CRM?

      Hello Zoho CRM Community, I’m looking to customize Zoho CRM to send a custom alert whenever a task is created. I understand that Zoho CRM supports client scripts using JavaScript, and I would like to leverage this feature to implement the alert functionality.

    • Deleting Views

      How do you delete views? Please syd

    • Fixed Assets

      Where would I manage my fixed assets

    • Create a purchase order in vendor's currency

      I am having a problem working this out and would appreciate some suggestions. We have Books and Inventory working in tandem. We are in Australia, our product is sold in Australia in $A and obviously all our invoices, accounts and reports need to be in

    • Report on Assets

      Hi,  Is it possible to report purchased assets on a specific year? The Balance Sheet shows everything up to the current date, and the expense reports will not show purchased assets because they are assets not expenses. If it is not possible, then is it possible to setup an API connection with Books to extract data from to another Reporting application?

    • Purchase of Fixed Assets

      How can I record the purchase of assets using zoho books? For example, I purchased 4 laptop for 100000 $ each and paid it through my bank account. How can I record this transaction and maintain track of how much of the assets I bought?

    • Where is the Fixed Asset Register?

      I am a Zoho One user for 18 months, using invoicing and CRM and now ready to migrate my books to Zoho Books. Where do I keep the fixed asset register for the equipment that I use in my business? I have a service based business with a lot of gear and business

    • Fixed assets recording

      Hello there, I recorded a bill for a vendor contain (Computer) so the PC is a fixed assets, do I need to do a manual journal to include this PC under the fixed assets category (furniture & equipment)? If yes, please take me through the manual journal

    • Zoho CRM functions editor is not in the programming language deluge

      I am trying to write a function for a button. I helped someone before in deluge and I'm using this new editor I'm not familiar with - I guess it is new. Why is the default code statically typed? The editor will not let me create a variable without a type.

    • [New Release 2024] Create and embed custom capabilities across CRM with Kiosk Studio, our latest no-code tool

      [Update | New series] We've started publishing a series of posts on Kiosk Studio. It's called Kiosk Studio Sessions and you can check out the first one here! [Update | 15 Oct} Session #2 is live! This one will look at how to create a kiosk for your call

    • Multi-Select lookup field has reached its maximum??

      Hi there, I want to create a multi-select lookup field in a module but I can't select the model I want the relationship to be with from the list. From the help page on this I see that you can only create a max of 2 relationships per module? Is that true?

    • Kaizen #168 - Incremental Authorization

      Welcome to this week's post in the Kaizen series. In this post, we will discuss Incremental Authorization. What is Incremental Authorization? Incremental Authorization is an OAuth strategy that allows a client to request specific authorization scopes

    • Configure Notes Title for Blueprint Transition

      It'd be very helpful to be able to configure note titles on blueprint transitions when requiring notes. This would help tie back the history of notes to the blueprint actions. We have some approval processes in our blueprint and require notes for the

    • An update to improve email delivery | Email Authentication & Relay

      Dear Zoho Recruit Community, We hope this message finds you well. This post is to inform you about an important update regarding the authentication of all email domains in your Zoho Recruit account. Effective 31st December, 2024, emails sent using email

    • How to Customize Task Creation to Send a Custom Alert Using JavaScript in Zoho CRM?

      Hello Zoho CRM Community, I’m looking to customize Zoho CRM to send a custom alert whenever a task is created. I understand that Zoho CRM supports client scripts using JavaScript, and I would like to leverage this feature to implement the alert functionality.

    • Stop adding Default ID column to xls exports

      When anything is exported to xls, Zoho adds a column with an ID.  WE DO NOT WANT THIS COLUMN.  We use an automated report to a team.  We have our own tracking number.  1. This makes the report messy, it just pushes OUR data off to the right.  2. We have

    • Automation#25: Move Tickets to Unassigned When the Owner Is Offline

      Hello Everyone, Welcome to this week's Community Series! 'Tis the holiday season—a time when work often takes a brief pause. The holiday spirit is in full swing at Zylker Techfix too, with employees taking some well-deserved time off. During this period,

    • Zoho cases and remote work api

      How to use zoho cases listing api? When i try to hit the endpoint specified in the docs , i get the error : the page you are looking for does not exist with a 401.

    • Calendly does not show scheduled Meetings

      I use Calendly as my standard booking tool, but no matter what I am doing, Calendly shows any appointment as free (when in fact there already is an appointment in CRM Calendar or Zoho Calendar). Drives me nuts - cannot go away from Calendly due to various

    • Delete Field that is used in a Zoho Flow connection

      I'm trying to delete a Field used in a Webhook created by Zoho Flow with CRM Connection and i get the following alert: When going to the alert i get to the following issue, can't edit it since its been deployed by a pluggin But yes i have here the prompted

    • I want the currency in my account to be Mexican pesos.

      Hello, I am a Mexican citizen and live in Ukraine. When I registered to your system, it was seen that I was from Ukraine, so the default currency is Euro. This is causing me a problem. Please change the standard currency in my account to Mexican Pes

    • Directly Edit, Filter, and Sort Subforms on the Details Page

      Hello everyone, As you know, subforms allow you to associate multiple line items with a single record, greatly enhancing your data organization. For example, a sales order subform neatly lists all products, their quantities, amounts, and other relevant

    • Year-End Wrap: Don't rewrite - Switch to Email Templates

      As we're half-way through December, now is the perfect time to start sending out festive greetings. Whether it is to your clients or your team, it is important that every mail is tailored to the recipient and feels genuine, which allows you to make better

    • Elevating Email Security on Zoho Desk: DKIM Now Mandatory

      Hello Zoho Desk Users! It has been a wonderful journey with you on Zoho Desk. As we prepare to welcome 2025, we are strengthening our efforts to ensure a secure and seamless experience for you. To enhance email security, DKIM configuration will be mandatory

    • How to view shared mailbox in Outlook

      How to view shared mailbox in Outlook or in another software

    • Clear String field based on the value of other field

      Hello everyone, We would like to be able to clear a string field (delete whatever has been written and make it empty) when another field (picklist) is changed to a specific value. While I can empty other types of fields, I noticed that I can't do this

    • Necesito el código ZB para mi cuenta

      Hice cambio de servidor y no encuentro el codigo unico de cname.

    • Privacy error

      Privacy error on Chrome for all embedded forms and reports, this is a huge issue: "Your connection is not private Attackers might be trying to steal your information from creator.zohopublic.com (for example, passwords, messages, or credit cards). NET::ERR_CERT_COMMON_NAME_INVALID"

    • Email with attachments saving attachments into Zoho CRM from Zoho Mail

      Hi, I get a lot of emails from prospective clients asking if we would bid their project. Those projects usually have many documents associated with them that I link to.  I would like to have those documents be saved as an attachment in my Potential or Contact or Account. I don't see a way to do that that isn't multi-step. As of now I do the following: 1.) Open email 2.) If email sender isn't in my Zoho CRM database I enter them creating a Potential 3.) I download the attachment and save it to a different

    • Bug - OTP (email) and No Duplicates

      Scenario: Form with an email field, Validation: "No Duplicates" (because I want to ensure 1 entry per email). Embedded form into website (JS option). Enabled email based OTP. 1st test (via my website) - entered my email address - sent OTP - entered pin,

    • Customise Search Bar in CRM

      Is there a way to customise this search bar in the CRM to add fields?

    • Counting downloads of a file

      Hello Could anyone help me, I would like to use a custom script to count how many times a file contained in a record has been downloaded. Is that something that is possible in Creator? Thanks Estelle

    • Is there any way to prevent emails from being sent from zoho crm without pressing email opt out?

      When I left my desk yesterday I excitedly thought I had fixed my problem, by making use of the "Inactive" field ... However after contacting the support chat, they have advised to stop emails being sent I need to update the "Email Opt Out" field - which

    • New Search Function

      Hey Team, The search function updated in our CRM about a week ago, so I assume it was an automated update across Zoho. It no longer displays leads/deals etc in Chronological order so that the most recently created or updated is the first to display which

    • Next Page