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

    • Bulk Delete Customer Contacts.

      Due to a config issue on my end (my fault), I have ALL contacts from CRM imported as contacts in Books. Some clients have 30+ contacts. Is there a funky way to bulk delete? Each contact has three clicks and a scroll to delete them.

    • Multiple domains for same username and password

      I've come across this situation the vault is currently suggessting the passwords autofill option by the domain. wondering whether is there any option to save one password for multiple domains since the microsoft login has two domains https://login.microsoftonline.com/

    • Introducing Bot Filtering for Accurate Email Campaign Analytics

      Dear Marketers, We're excited to announce a new feature designed to enhance the accuracy of your email campaign analytics: bot filtering. This feature helps you filter out bot-generated opens and clicks, ensuring your campaign reports reflect genuine

    • Option to specify or disable "Idle" times in preferences

      It seems strange to me that my Cliq shows me as "Idle" when I'm using the PC and available just because I haven't interacted with Cliq in a while.  I'm far from "Idle" so we're just treating "Idle" and "Available" to mean the same thing.  I'd like to suggest a setting to change the timeout or even disable the automatic "Idle" mode.

    • Lockable Due Dates

      Hello, is there a way to FIX due date of task or task list, so that they cannot be moved by linked task that are late? Like having a sort of "limit date" that would create an alert if not reached?

    • in zoho books while categorizing need to add new name in category by replacing expanses how to edit or make changes need assistance

    • Function #61: Automatically add free item to the invoice based on item quantity

      Hello everyone, and welcome back to another Custom Function Friday! During holiday seasons or special promotions, businesses offer deals like BOGO (Buy One, Get One), Buy 3 Get 1 Free, Buy 2 at 50% off, and much more to attract customers. These promotions

    • Regarding GST Report Issue in Zoho Books

      Hi, Right now, the very important point from my end is this Zoho Books issue. Here, you can see that we have created the invoice with the items of account sales and expenses. The journal is also correct. The profit and Loss statement is also correct.

    • Multiple Salesperson against an invoice

      Hello, Against a particular invoice, we have multiple sales people working. The reason we combine the invoice is becuase we are an exporter and often consolidate cargo for our customer to save them freight costs. How do I capture the contribution of each

    • Projectwise budget ---

      Can we have a Project wise subject in addition to the Monthly, and quarterly ACCOUNT LEVEL budget?

    • Looking back at Zoho Social's 2024: Highlights and memories

      Hey everyone, We hope you had a relaxing and joyous holiday season. Whether you're planning for the new year or still soaking in the magic of the season, we're here to share some exciting highlights from 2024 – a year that was fully packed with updates

    • Building a Zoho Extension for Webex CC - Handling URL Changes

      Hi everyone, I’m building a Zoho extension for Webex Contact Center (Webex CC) and facing an issue with handling URL changes. In telephony, I’ve set the URL of Webex CC to: https://desktop.wxcc-us1.cisco.com/ When this URL remains the same, everything

    • Remove County field from Customer Address input screen (or allow input to be deleted)

      We are in the USA and have just noticed that there is now a County field in the Customer Address input screen (and maybe other areas of Zoho Books, but this is the one affecting us at the moment). County is not important to our business, and in fact we

    • Zoho still running very slow

      I have a lead log for my company and creator seems to be running extremely slow still.

    • Bigin API Token Request ("invalid_client")

      Hi people, I tried to connect to the API without success, I've read all of the documentation multiple time and tried just about everything. I tried to do it with Python Request module and with Postman, passing the information through both the URL parameter

    • Shared Dashboard / Report Permissions : Read not Write

      hi all, We are missing a huge fonctionnalite in setting up Dashboards (and reports) on corporate level.  Currently, we can not set Read Permissions on share Dashboards (and reports) without giving write access as well When we create a corporate dashboard

    • Profile stitching with Zoho Marketing Automation

      When it comes to marketing, knowing who your audience is and tracking their interactions is vital. That's why Zoho Marketing Automation has taken a significant leap forward with its enhanced profile stitching feature. With this update, you can track your

    • GDPR

      Hi , I'm checking out the HIPPA capabilities and at the moment I can see only three modules that can be selected to enable HIPPA Any idea how I can add additional modules such as customers? TNX David

    • default task list for new project

      Is there any way to have a default task list already created in a project, when the project is created in Zoho Books?

    • Record less quantity than ordered in ZOHO inventory

      Lets say I ordered 100 widgets from a Vendor. I have paid the Vendor month ago and just waiting for the product to ship. I have finally received the products but have only received 80 widgets. I see no way in ZOHO to only receive 80 widgets. ZOHO is forcing

    • Stripe payments via Books invoice link missing email - affects fraud detection

      Hi, All our payments done via Books invoice link have a warning: Integration improvement available This transaction is missing customer email address, which affects fraud detection. Why doesn't Books pass this info to zohosecurepay.eu/books/... for more

    • Power of Automation: Automatically sync custom field data between two tasks.

      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:-

    • 'View Invoice' button hyperlink taking to Google Business Maps listing

      The green "view invoice" button in my invoice emails is sending people to my Google maps business listing rather than the invoice. Both my clients and I are experiencing this as a new issue.

    • Migrating Zoho emails to Google Workspace

      Hi Is there a tool to migrate Zoho email to Google workspace?

    • Custom Functions - Calculate Commission - failure after migration from US to EU

      Hello, i would ask for help. My Custom Function - Calculate Commission stopped working and shows a failure. Mismatch of data type expression. Expected List but found String What is the problem? Could anyone help? Here is script: void automation.ObliczProwizje(Int

    • GoCardless Mandate Sync Question

      Hello, When syncing our customer database with GoCardless, some customers aren't working despite both email addresses matching in Zoho Books and GoCardless. Also what do we do about customers where they are associated with multiple accounts as these aren't

    • Create a draft in reply to an email via Emails API

      Hi, I’d like to use the outgoing webhook to automatically create a draft reply to incoming mail. How can I use the Emails API to create a draft reply that is linked to an existing email thread? I couldn’t find the relevant method in the documentation.

    • Weekly Tips: Flags for an organized mailbox

      Wishing you all a Happy New Year 🎉 As we step into 2025, it's time to refocus and set our intentions for the year straight. Whether you're already back at work or just returning from the holidays, you probably have emails that need your immediate attention,

    • Edit line item amount

      It would be sooooo much better to be able to edit the line item amount in all of the modules, if there is any variation in agreed prices it's extremely painful to calculate the rate to match ;-( The rate could be auto calculated on editing this field making life so much easier !

    • Chanel Partner

      Any Zoho channel partner or dubai based company who will help us for getting zoho services including the training for our staff

    • Refer a Friend Campaign

      I am looking to run a referral campaign that sees an initial email going to existing clients, asking them to refer a friend. For each new client referred, the existing client will get a ticket in a prize draw - the more new clients they refer, the more tickets they get in the draw.  I am wanting to figure out how this could be done via Zoho, and how these referrals can be tracked and linked to the existing client who referred them.

    • Emails cannot be received

      Hey, There is an issue in my Zoho account, E-mails can be send from my side but cannot be received on my account MX, DCIM and other are added but still cant receive them. Please help me to solve this problem at your earliest convenience and this is happening

    • Newsletter in multiple languages

      Hi We are planning on starting to use Zoho Campaigns for our newsletters. Since we send our newsletters in three languages, I would need the "unsubscribe page" and other pages related to the NL (Thank you page and so on) to be available in different languages

    • i couldn't recall message as one of the receptionists didn't received the message and i want to recall it urgent

      i couldn't recall message as one of the receptionists didn't received the message and i want to recall it urgent as recall button doesn't appear

    • Servidores caidos?

      Buenas, Hoy 30/12/2024, mi empresa esta sufriendo bastante problemas para acceder a las aplicaciones de Zoho. No sabemos si es solo nuestra compañia o esta afectado a todos. Cuando intentamos acceder a las aplicaciones nos salta el siguiente error: A

    • Tip #1- Remote support vs. unattended access: Contrasting two key concepts in tech assistance- 'Insider Insights'

      Hello everyone! We, at Zoho Community, are excited to introduce Insider Insights, a new series where we will look into various aspects of remote support technology and how they might help you. We'll be sharing tips, methods, and insights acquired from

    • Introducing Fair Evaluation for Interviews

      Collaboration is key in recruitment, but it’s important to ensure individual interviewers’ assessments are not influenced by others. With Fair Evaluation, you can choose how and when interviewers can see reviews of a candidate for the same job opening.

    • I have been looking for CVID to get segmate list where & how can fnd it?

      I am trying to get segment details from the Zoho API. The API documentation says that the CVID is a mandatory parameter, but I cannot find the CVID in the "getmailinglists" API. Can you tell me where to find the CVID?

    • "The data you have entered already exists" when trying to create contac@mydomain.com

      Hi all, Our domain is ananasjuicebar.com. Working as admin in the control panel: When I try to add the email account "contact@ananasjuicebar.com" I get the error: "The data you have entered already exists" I've tried creating a new user or creating a new group with this address associated. To my knowledge this address has never been added and I can also not find any reference to it. (Shopify used this address to send customer notifications BEFORE setting up Zohomail.) Any ideas? are there any restrictions

    • Tip of the week 03 - Sending emails in batches

      Today's marketers not only want their email marketing to be efficient, but also smart. For an email campaign, you may think you have all the essential elements for lead conversion—a big mailing list, an attractive template design, and the most-engaging message content, but after hitting the ‘send’ button, you may not get the expected conversions. Wondering why? Here’s one of the major reasons. Many marketers miss out on sending the email campaign the right way. Did you know that you should not be

    • Next Page