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

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

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

    • Display your zoho contact name when they call your mobile number

      As per the title If a contact calls the office number, the contacts name shows on mobile as long as I have their contact details registered in my crm. Is there a way that if the contact calls my mobile, their name can be displayed? Currently just their number shows when they call.

    • Change script to add fields

      Hi, I have a custom function (writen by a different implementation company in the beginning) which I would like to edit to add a different field as well. Can't get it to work on my own though. - The script now adds the address fields to a new quote (needs

    • 1 API to all channel

      hi zoho team: I am the product manager of anywheel, we are planning to integrate zoho, we want to integrate multiple channels through 1 API, please can you send me the integration document and guideline?

    • 🎄 Jingle, Mingle, and Automate: Spread Christmas Cheer with Zoho Desk Auto-Replies! 🎄

      Hello Everyone! Welcome to this week's episode of the Community Learning Series. Christmas is in the air, and I’m sure we can all feel the jingle and the mingle of the season! The folks at Zylker Techfix are no exception—they’re busy with holiday plans

    • Macro Email to be determined by a ticket field

      Hi, we are a commercial energy brokerage and are implementing Desk as our helpdesk tool to replace manual emails, personal whataspp and telephone. We have setup a macro rule when we can trigger an email, update ticket status and trigger a task.... but

    • Custom Profile Agents Unable to Update Mandatory Phone Number in tickets under Zoho Desk

      Hi, While working in the Ticket module in Zoho Desk, agents with a custom profile are unable to update the Phone Number field (which is mandatory) under Account Information. The agents need to enter values such as "NA" or "Nil" in the field to close the

    • Revamped Print in Zoho Sheet—customized for paper

      The latest enhancements to Zoho Sheet's Print settings allows you to print a worksheet or a selected range, with customizations that make the data comprehensible, even on paper.   Customize header and footer Make your spreadsheets meaningful with a relevant header and footer. You can now choose to display the file name, sheet name, current page number, total pages, date, and time as the header and footer in your print view. Besides the predefined elements, you can also give a custom text for header/footer.

    • Adding Bluesky channel

      Hello, Is Bluesky (AT protocol) soon added on Social ? Bluesky is being developped and is now open to anyone (no more invitation) Thank you

    • How Can i put a form in Zobot

      Hi,how can i integrate a form which has a multiple options to choose from.the form should be opened or displayed by zobot after it meets a requirement in the conversation. Thanks in advance !

    • Query table pull last 12 months

      I am tying to pull the following criteria and the date is always what causes me the issue. I want to pull people (pco_id) who have entries of "event_id" being these 2 events and whos "kind" is Regular or Guest and where the event_starts_at (date column)

    • 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 that

    • Response Violation - Zoho Desk

      Hi Team, I just need an information regarding the zoho desk - Response Violation and how can we avoid the tickets from getting the tickets response violated.

    • message on click of button

      Hi, i added insert task on 'Quick view' below  'Action'  of report just below 'Delete' button,  so i am trying to add a message on click of button that, "This item is now added into Pending Request" like this .... So, how can i achieve this ; because

    • Is it possible to disable Chat Waiting Time, or to make it indefinite?

      We have used many online chat services over the years. However, Zoho's SalesIQ appears to be the only one we've tried that has a mandatory time limit where we must respond to new customer queries. We are a small business so we have no dedicated staff

    • Access CRM Variables from Formula field

      Is it possible to use a CRM variable (defined in Developer Space -> CRM Variables) in a formula field for calculations ?

    • Client Script: $Client.refresh({ triggerOnLoad: true }); not triggering onLoad Client Scripts

      Hey friends! I'm trying to store a temporary var, refresh the page for the user, then check that temporary var and do some actions. Theoretically using the title's code: $Client.refresh({ triggerOnLoad: true }); should refresh the page and trigger on

    • Super Admin login to delete certain folders and passwords and clearing the trash folder, they are still appearing on my dashboard

      Hi Zoho Team, I need help with an issue I've encountered. Despite using the Super Admin login to delete certain folders and passwords and clearing the trash folder, they are still appearing on my dashboard. I would like to understand why this is happening

    • Pulling Specific Products from Sales Orders in Books to a CRM Record

      We currently process orders directly through our website (woocommerce) as well as through manual sales orders in zoho books. When an order comes through the website, all of the individual products from that order show up in the CRM record of that customer.

    • Automatically add a retainer to every estimate

      Hi all, I've been trying to find a way to automatically add a retainer at a set % to every estimate we create and send. So far I haven't been successful, does anyone know of a way to do this? Thanks,

    • 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

    • 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 be

    • Within the Basic KPI component in Analytics, it is impossible to set "next" day range as a filter

      Hi there, I am currently setting up a deal dashboard for the Sales team. While it is possible to filter deal records to show records that were created LAST X days only, it looks like a NEXT X days Closing date filter is not available. Would it be possible

    • Invoice status on write-off is "Paid" - how do I change this to "Written off"

      HI guys, I want to write off a couple of outstanding invoices, but when I do this, the status of the invoices shows as "Paid". Clearly this is not the case and I need to be able to see that they are written off in the customer's history. Is there a way

    • For each loop with available time slots

      I am very new to Deluge, and this question was unable to be answered by Zoho Creator tech support upon request. Task at hand: I have a Form with 4 fields: - Date Start - Date End - Dropdown: Time Start: contains time slots (12:00PM, 12:15PM, etc) - Dropdown:

    • Can we have Backorder Management ?

      Can we have Backorder Management ?

    • Converting Amazon Sales Order to Invoice

      Hi there, We need  advice on the Amazon integration with Zoho Inventory. Now, we want to convert all the Sales orders synced from Amazon to Invoices. We want also to include and record the Amazon fees associated with the sales (Amazon fees, FBA fees, Cost of Advertising etc.) However, Sales order only captures the sales proceeds (Gross Sales) in Zoho Inventory. Does anyone currently work with Amazon and can suggest how to correctly process the sales and Amazon payments through Zoho Inventory and

    • Zoho Inventory | Can't uncheck/turn off Advance Tracking

      Hi, I wanted to know if there's a way to turn off Advanced Tracking (such as Serial Number or Batch Tracking) for an item in Zoho Inventory. I’ve read that you might need to delete associated transactions and clear the opening stock to disable these features.

    • No Hope for Zoho Meeting

      Zoho Meeting is just the poorest meeting app I've come across in a long time. The support sucks too. I called to see if there was anything that could be done on the backend and while I was on a test meeting with support the video was lagging and freezing

    • Landed Cost application to Vendor Bills from dropship Purchase Orders

      When trying to apply a Landed Cost to a Vendor Bill generated from a dropship Purchase Order, the Landed Cost pop-up window generates a message that "Landed Cost cannot be applied to Bills from dropship Purchase Orders" when trying to save the landed

    • Condition-based data sharing rules are now available in CRM

      Dear All,   We are excited to introduce a much awaited feature: condition-based data sharing rules. We'd love to explain more about this enhancement.   Specify record conditions in data sharing rules Data sharing rules enable you to share all the CRM

    • 2 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 numbers

    • Zoho Projects Roadshow, USA - 2024

      Dear Users, We are happy to announce the Zoho Projects Roadshows 2024 in USA. This is an excellent opportunity to learn more about Zoho Projects and gain in-depth knowledge of the advanced features. Our team will also discuss industry specific solutions

    • [Zoho Writer Webinar] Tips on collaboration control in Writer

      Hi Zoho Writer users, We're excited to announce the Zoho Writer webinar for the month of October 2023: Tips on collaboration control in Writer. This webinar will help you understand the various features available in Writer to control collaboration. We'll

    • [Zoho Writer Webinar] Working with tables in Zoho Writer

      Hi Zoho Writer users, We're excited to announce the Zoho Writer webinar for the month of September 2023: Working with tables. This webinar will help you understand the various ways you can use tables to meet your specific needs. The webinar will take

    • [Zoho Writer Webinar] Customize Writer to suit your business process

      Hi Zoho Writer users, We're excited to announce the Zoho Writer webinar for the month of August 2023: Customize Writer to suit your business process. This webinar will cover the various ways to customize Writer to streamline business processes and improve

    • Why is Zoho Meeting quality so poor?

      I've just moved from Office 365 to Zoho Workplace and have been generally really positive about the new platform -- nicely integrated, nice GUI, good and easy-to-understand control and customisation, and at a reasonable price. However, what is going on

    • Is there a way to print the dashboard?

      I would like the capability of printing the dashboard - is that possible?

    • Workflows for Timesheet

      Good day, Any way to have timesheet as triggers? I looked into Zoho Flow and into Zoho Project automation but no where can I have timesheet as a trigger. Basically, I would like to trigger something upon timesheet approval. Right now, the only way to

    • Linkedin - Recruiter System Connect

      Hi there! Does anyone here know how to connect Zoho Recruit to Linkedin Recruiter via Recruiter System Connect?

    • Next Page