Kaizen 81 - COQL API - Part II

Kaizen 81 - COQL API - Part II

Hello everyone! 
Welcome to another week of Kaizen! 
In continuation to last week's post on COQL API, we will discuss the rest of the field types and their supported operators with detailed examples in this post. 

Supported field types and Operators

Please refer to the COQL API - Part I Kaizen post for the first three field types and their supported operators.

4) Boolean

The supported operator for Boolean field is =. You should provide the value as either true or false.

Sample Query

{
 "select_query" : "select Product_Name, Product_Code from Products where Product_Active = 'false' limit 2"
}

This sample query selects the Product_Name and Product_Code fields from the Products module where Product_Active is false, and limits the result to only 2 records.
Sample Response:
{
    "data": [
        {
            "Product_Code": "SR-001",
            "Product_Name": "Sigma",
            "id": "4876876000001036109"
        },
        {
            "Product_Code": "SR-003",
            "Product_Name": "Alpha",
            "id": "4876876000001039006"
        }
    ],
    "info": {
        "count": 2,
        "more_records": false
    }
}

what_Id support in COQL

=, !=, in, not in, is null, is not null are the supported operators. what_Id support is extended only to Tasks, Calls and Events. The what_Id field could be a lead or a contact.

Sample Query

{
    "select_query": "select 'What_Id->Leads.Last_Name' from Tasks where (('What_Id->Leads.id' in ('4876876000000900134','4876678000000900987')) AND ('What_Id->Leads.Industry' != 'ERP'))"
}

This sample query queries for the last name of leads associated with tasks where the lead ID is either '4876876000000900134' or '4876678000000900987', and the lead's industry is not 'ERP'.
Sample Response:
{
    "data": [
        {
            "What_Id->Leads.Last_Name": "Perry",
            "id": "4876876000001103044"
        }
    ],
    "info": {
        "count": 1,
        "more_records": false
    }
}

Roles and Profiles support in COQL

COQL supports roles and profiles lookup fields, allowing users to retrieve the owner's profile details such as ID, name etc, and the owner's role details using COQL queries. The supported comparators are =, !=, in, not in, is null, is not null.

Sample Query

{
    "select_query": "select Owner.role.id,Owner.role.name,Owner.role.reporting_to, Owner.role.share_data_with_peers, Owner.role.description, Owner.profile.id from Leads where Last_Name is not null LIMIT 1"
}

This query fetches the Profile details and Role details of the owner of one record from the Leads module. 

Sample Response:
{
    "data": [
        {
            "Owner.role.reporting_to": null,
            "Owner.profile.id": "4876876000000026011",
            "Owner.role.name": "CEO",
            "Owner.role.description": "crm.security.role.admin.desc",
            "Owner.role.share_data_with_peers": true,
            "Owner.role.id": "4876876000000026005",
            "id": "4876876000000333403"
        }
    ],
    "info": {
        "count": 1,
        "more_records": true
    }
}

Alias support

Supported operators : =, !=, in, not in, is null, is not null
Alias support in COQL allows users to simplify complex SELECT field names by giving them custom names or aliases. Using aliases in the SELECT column and ORDER BY class can make column names easier to understand and remember. For instance,  What_Id->Leads.Last_Name from our previous example can be given an alias in the SELECT query as follows.

Sample Query

{
    "select_query": "select 'What_Id->Leads.Last_Name' AS 'Lead Name' from Tasks where (('What_Id->Leads.id' in ('4876876000000900134','4876678000000900987')) AND ('What_Id->Leads.Industry' != 'ERP'))"
}

Sample Response:
{
    "data": [
        {
            "id": "4876876000001103044",
            "Lead Name": "Perry"
        }
    ],
    "info": {
        "count": 1,
        "more_records": false
    }
}

If you compare this response with the sample response in the what_Id section above, you can see that the key 'What_Id->Leads.Last_Name'  is replaced with the Alias 'Lead Name'  in here. 

Aggregate Function Support in COQL

Aggregate functions in COQL allow you to perform calculations on groups of records in a module. The available aggregate functions include SUM, MIN, MAX, AVG, and COUNT.

1. SUM

Use this function to sum up the values of an aggregate field in a module. 

Sample Query 1

{
    "select_query":"select SUM(Grand_Total) from Quotes WHERE Quote_Stage = 'Draft' "
}

This Query uses the SUM function to calculate the total value of the Grand_Total field for all quotes in the Draft stage in the Quotes module.
Sample Response:
{
    "data": [
        {
            "SUM(Grand_Total)": 1073660
        }
    ],
    "info": {
        "count": 1,
        "more_records": false
    }
}

Sample Query 2

{
    "select_query": "select SUM(Grand_Total), Account_Name.Account_Name AS 'Account Name', Billing_Country from Invoices where ((Status != 'Paid') and ((Billing_Country ='USA') OR (Billing_Country = 'Canada'))) GROUP BY Account_Name.Account_Name, Billing_Country ORDER BY 'Account Name' ASC"
}

This query retrieves the total SUM of the Grand_Total field, along with the Account_Name and Billing_Country from the Invoices module for those records whose Status field is not equal to 'Paid' and the Billing_Country field is either 'USA' or 'Canada'. The results are grouped by the Account_Name and Billing_Country fields and ordered in ascending order based on the 'Account Name' field.

Note that the 'Account Name' field is specified using the AS keyword to provide an alias for the Account_Name.Account_Name field. We have used the alias for the ORDER BY clause.
Sample Response:
{
    "data": [
        {
            "Account Name": "SR Systems",
            "Billing_Country": "USA",
            "SUM(Grand_Total)": 2430000
        },
        {
            "Account Name": "SR Systems",
            "Billing_Country": "Canada",
            "SUM(Grand_Total)": 60000
        },
        {
            "Account Name": "Zylker systems",
            "Billing_Country": "Canada",
            "SUM(Grand_Total)": 378000
        }
    ],
    "info": {
        "count": 3,
        "more_records": false
    }
}

The response JSON contains the SUM of the Grand_Total fields, Account Name and Billing_Country for each unique combination of Account Name and Billing Country fields that satisfies the filter criteria specified in the query. 

2. MAX

Use this aggregate function to find the largest value of a field in a module. 

Sample Query

{
    "select_query": "select MAX(Amount) AS 'Maximum Deal Amount', Account_Name.Account_Name from Deals where ((Stage = 'Closed Won') AND  (Type = 'Existing Business')) Group by Account_Name.Account_Name"
}

This Query selects the maximum Deal Amount for each account from the Deals module where the stage is Closed Won and the type is Existing Business.
Sample Response:
{
    "data": [
        {
            "Maximum Deal Amount": 6750000,
            "Account_Name.Account_Name": "Benton"
        },
        {
            "Maximum Deal Amount": null,
            "Account_Name.Account_Name": "King"
        },
        {
            "Maximum Deal Amount": 945000,
            "Account_Name.Account_Name": "Morlong Associates"
        }
    ],
    "info": {
        "count": 3,
        "more_records": false
    }
}

3. MIN

Use this aggregate function to find the smallest value of a field in a module. For example, you can use this function to find the Lowest Annual Revenue in the Leads module.

Sample Query: 1:

{
        "select_query": "select MIN(Annual_Revenue) from Leads where Annual_Revenue is not null"
}

Sample Response:
{
    "data": [
        {
            "MIN(Annual_Revenue)": 348.3
        }
    ],
    "info": {
        "count": 1,
        "more_records": false
    }
}

4. AVG

Use this aggregate function to find the average value of a field in a module. 

Sample Query

{
    "select_query": "SELECT AVG(Amount) AS 'Average Deal Amount' FROM Deals WHERE Type = 'New Business'"
}

This query calculates the average deal amount for all new business deals in the "Deals" module. 
Sample Response:
{
    "data": [
        {
            "Average Deal Amount": 877366.8359999999
        }
    ],
    "info": {
        "count": 1,
        "more_records": false
    }
}

5. COUNT

Use this aggregate function to count the number of records in a module satisfying a certain criteria. You can use this aggregate function only for number, lookup, and picklist fields.

Sample Query:

{
    "select_query": "SELECT COUNT(Product_Category) FROM Products WHERE Product_Active = 'false'"
}
This sample query queries for the total number of inactive products in the Product module. Please be aware that if there are any products with no value for the product category field, they will not be included in the count.

Important points to remember

  • COQL keywords are not case-sensitive.
  • To prevent ambiguity, the criteria listed in the WHERE clause must be properly enclosed in brackets. If WHERE has more than two criteria such as A, B, and C, use them as either of the following:
    • (A and (B and C))
    • ((A and B) and C)
    • A and (B and C)
    • (A and B) and C.
  • COQL supports only SELECT queries with WHERE, FROM, ORDER BY, LIMIT, and OFFSET clauses and aggregate functions SUM(), MAX(), MIN(), AVG(), and COUNT().
  • The default sort order is ascending based on record ID if ORDER BY is not specified.
  • Use the following format for :
    • Date : YYYY-MM-DD
    • DateTime : YYYY-MM-DDTHH:mm:ss+/-HH:mm
  • The default value for LIMIT is 200 and OFFSET is 0.
  • A maximum of 10,000 records can be fetched using the API.
  • Multi-line fields cannot be used in criteria.
  • COQL doesn't support consent_lookup, subform, profileimage, multiselectlookup, fileupload datatypes.
  • A maximum of 25 criteria can be included in the WHERE clause.
  • A maximum of 50 field API names can be used in the SELECT column of the query.

     Data Type
     Supported Operators
     text
     =, !=, like, not like, in, not in, is null, is not null
     picklist
     =, !=, like, not like, in, not in, is null, is not null
     ownerlookup
     =, !=, in, not in, is null, is not null
     lookup
     =, !=, in, not in, is null, is not null
     date
     =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
     datetime
     =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
     currency
     =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
     boolean
     =
     email
     =, !=, like, not like, in, not in, is null, is not null
     phone
     =, !=, like, not like, in, not in, is null, is not null
     website
     =, !=, like, not like, in, not in, is null, is not null
     double
     =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
     bigint
     =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
     integer
     =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
     formula
     If the return type is:
          Decimal/Currency/Date/Datetime : =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null
          String : =, !=, like, not like, in, not in, is null, is not null
          Boolean : =
     autonumber
     =, !=, like, not like, in, not in, is null, is not null
We hope you found this post useful. We will meet you next week with another interesting topic.

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! 


Additional Reading:











        • Recent Topics

        • KPI widget with percentage

          I'm trying to create a KPM widget that displays current performance as a percentage - something like the picture below. I've tried following the instructions at https://www.zoho.com/analytics/help/dashboard/kpi-widgets.html#chart but nothing ends up being

        • Canvas List View Not Saving

          Hi, I am trying to edit a list view to look different depending on the tags. Everything worked well and saved well with multiple views, but when I have gone back in to make some small changes like moving one of the icons it comes up with the error message

        • QR code image is not exported in PDFs

          The new QR code field works fine when I include it in a report template and I choose the print option: https://creatorapp.zoho.com/<username>/<app_link_name>/record-print/<report_link_name>/<record_ID>/ But when I try to save the document to a .pdf file

        • QR codes in templates

          I'm excited about the new QR code generator. I have included a QR code that contains the record ID setting "${ID}" as input data. In the report detail it works perfectly but when printing it in a template the code is not shown.

        • This mobile number has been marked spam. Please contact support.

          Hi Support, Can you tell me why number was marked as spam. I have having difficult to add my number as you keep requesting i must use it. My number is +63....163 Or is Zoho company excluding Philippines from their services?

        • Zoho CRM search not working

          The search bar is not showing any results in our CRM installation. We have a lot of items and can not search them by using the navigation each time. Can someone please check this asap.

        • Reload page with widget

          Hi all, I hope I can find some help here. I developed a small widget for Creator that is integrated into a page as a component. The page contains other content as well. When the widget is sent, the entire page should be reloaded to apply the changes to

        • Tip of the week #37 - Manage all your Telegram business conversations directly from your shared inboxes.

          Tired of switching between multiple apps to manage your business conversations? With Zoho TeamInbox's multichannel inboxes, connect your Telegram channel to a shared inbox. This way, your teams can easily handle c View, reply, and collaborate on them

        • Tags on notes aren't syncing correctly on Android

          I've created notes on the desktop version that have several tags assigned, but on both my Android devices those notes only have ONE of those tags instead of all of them, despite the actual content of the note being correctly synced, and I'm also starting

        • Reports - custom layout - duplicate report

          Do you also have this problem and what is the possible solution? I duplicate a report that has a "custom layout". Unfortunately the custom layout is not duplicated. To be improved for a future release by Zoho. I export the custom layout and import it...

        • How to map a global picklist from one module to another

          Hi there, i currently have a new field that is called sales office which we use for permission settings between our different offices located in different countries. It is a global set picklist with three different options: MY, SG and VN. I want to be

        • Pageless mode needed to modernise Writer

          When we switched from GSuite to Zoho, one of the easiest apps I found to give up, was Docs. In many ways, Writer has always been more powerful than Docs, especially in terms of workflows/fillable forms/etc. However, I went back into Docs because I notice

        • Changing the Logo Size on Zoho Sites

          My company logo incorporates both an image and text, and I would like it to be much more prominent on the page than is currently allowed by the small logo box in the template.  Is there any way to hide the page name and then make the logo box much bigger since my company name and logo are connected / are all in one file?  Thank you. 

        • Is it possible to Select Item Serial Numbers from a Sales Order?

          Our accepted estimates are converted to Sales orders for our warehouse staff to pick.  How can my warehouse staff select the serial numbers for an item when editing a Sales Order?  Logically when staff pull an item and have the serial in front of them they update the Sales Order and select the serial. I understand a serial can be added when creating an invoice but how can accounts team know the serial if the warehouse staff can't select it! A basic flaw!

        • MORE BUGS: Client Script, Deluge and Widget JS SDK don't work as expected when trying to retrieve a record that has been "rejected" as part of an approval process.

          Client Script $Page.record is null when accessing a record that has been "rejected" as part of an approval process. Deluge zoho.crm.getRecordById(moduleName, recordId) returns {"status":"failure"} when recordId is a valid, but rejected record. OK... I

        • Zoho CRM Widget not displaying 2 related lists (JS)

          Okay so I basically have 2 relatedLists that I want to get and render: ZOHO.CRM.API.getRelatedRecords({ Entity: data.Entity, RecordID: data.EntityId, RelatedList: "Notes", page: 1, per_page: 200, }) ZOHO.CRM.API.getRelatedRecords({ Entity: data.Entity,

        • Zoho Books and Zoho Projects Task Status Update

          How can we create an automation using custom functions for the following scenario. When our zoho books invoice status changes to paid. I want a task in Zoho projects to change to completed.

        • Assigning Tasks and Requests to Groups... how do I?

          Guys, I've spent many hours exploring Zoho Support and we are generally satisfied with the system.  I'm trying to understand how a system that has so much to offer can be missing GROUP assignment and queue functionality.  I am hoping that there is a way

        • Parsing of SQL query failed. Please check the SQL syntax.

          I am trying to have Zoho Analytics recognize that if the a Deal is in Stage "Need Docs" it should also be counted as a Deal in the Stage "New Lead" /*New Lead*/ SELECT "ID" 'New Lead' AS "Stage" From "Deals" Where "Stage" = 'Need Docs' Union All Error

        • Where is the setting to enable/disable 2FA?

          The following links show where enable/disable 2FA is supposed to appear, but neither appear for me: https://help.zoho.com/portal/en/kb/zohosites/faq/account/articles/how-do-i-enable-or-disable-two-factor-authentication-for-my-account shows Security >

        • How to Assign Record Ownership in a Custom Form via API?

          Hello everyone, I’ve created a custom form in Zoho People and I’m using the API to manage its records. I would like to know how I can assign ownership of these records to specific users via the API. Is there a specific parameter or field in the API request

        • Customer Statement Template not matching when sending

          Hi everyone! So when I send statements to our customers via Zoho Books, the message that appears by default does not match what I have written on the template Under settings -> email notifications -> sales -> customer statement We have a single default

        • Peppol Malaysia API

          Hi Zoho Books, my country Malaysia will going to implement "Peppol" (E-Invoicing), starting 1 Jul 2025 for all businesses. The government intends to provide API for accounting app. The workflow involves creating an invoice from accounting app, triggers

        • Re-emitir facturas con nueva dirección de facturación

          Hola, necesito saber si es posible que las facturas ya emitidas, pueden ser re-emitidas con el cambio de dirección de facturación, realizado el día de hoy 02-01-2025, para efectos contables. Espero su ayuda, Gracias

        • Zoho Learn vs. Trainer Central

          Hi, I'm currently using Zoho One with a WordPress-based website and WooCommerce to manage my online courses. I would like to know what is the difference between Zoho Learn and Trainer Central and if it's possible for these two platforms to replace WP

        • Map Plan to Different Income Account for Some Subscriptions via API

          We have a plan that has a default Plan Account of "Sales". Can we override the account for a specific subscription via API? In some instances the same exact plan should map to a different income account. When we create stand-alone invoices in Zoho Books,

        • Flow with CRM

          Hello, I have a simple flow that uses a web hook to enter data into a Sales Order. I have the web hook sending Flow data which has a PO field. If the PO has a special character like - or / or \ the task fails. How can I get the flow to be okay with the

        • Chrome browser issues. Anyone else?

          I am suddenly having multiple issues with Chrome browser interpreting the Zoho Mail interface.  Anyone else?  Any known problems? Thanks, Todd

        • Zoho Payroll US?

          Good morning, just reaching out today to see if there's any timeline, or if there's progress being made to bring Zoho Payroll out to be available to all states within the USA. Currently we're going through testing with zoho, and are having issues when

        • Set up multiple IMAP email addresses

          Hi, I just started using CRM and its great, but I just found out I can only add one imap email address for incoming mail in the included salesinbox ...this is ridiculous. All companies have different email such as sales@domain, info@domain , personal@domain

        • Function 58: Custom calculation in item table of invoices (2 fields)

          Hello everyone, and welcome back to our series! In Zoho Books, the Item Amount in invoices is calculated by multiplying the Quantity and Rate fields. Previously, we shared a function to include a custom field in this calculation. Today, we are taking

        • Tracking new lead response time

          Hi, I have a team of Sales Development Reps, who have a KPI of responding to a lead within 20 mins or less once it hits the system.  I seem to recall that Zoho CRM had the capability to track this in a previous version, but don't see it anywhere.   It's

        • Search function not working anymore

          Hi! The search function is not working anymore. How can we solve this problem?

        • When converting a lead to an account, the custom mandatory fields in the account are not treated by zoho as mandatory

          In my Account module I have a number of custom fields that I have set as mandatory. When I enter a new customer as a new account they work, I can't save the record without populating them. However when I convert a lead, my CRM users are able to save the

        • Expand Zia's Language Support and AI Capabilities

          Dear Zoho Desk Support, I would like to submit a feature request to improve Zia, the AI-driven support assistant in Zoho Desk. Currently, Zia only supports the English language, while other AI agents such as Gemini, ChatGPT, and Claude can work with a

        • get gettting the days number between two dates with deluge

          I am trying to calculate the days number between 2 specific dates but its not working. PLease help me.

        • Limit excceding issue in zoho creator

          I am transferring data from Zoho Books to Zoho Creator using a Deluge script. However, I am frequently encountering a "limit exceeding error," which seems to be related to the Deluge statements limit. I reached out to Zoho Support, and they informed me

        • How do I add more schedules to Zoho Creator?

          At the moment, the number of schedule calls we have in Zoho Creator are 1800 per month and I was wondering if it was possible to upgrade that amount to something higher. I'd like to know my options as well as the pricing.

        • Conexion CREATOR x CRM

          Buenas tardes, Tengo un problema con un código que crea un registro en CRM. Revisé el CRM para eliminar los campos obligatorios, pero cuando ejecuto el programa, aparece el siguiente mensaje de error: {"code":"MANDATORY_NOT_FOUND","details":{"api_name":"data"},"message":"required

        • Invoices with billable time and expenses

          I cannot seem to get a straight answer. We are looking to create an invoice to send to our clients, but it needs to have the following on it: 1. Billable hours for each employee. All hours for the pay period on one line, by employee. 2. Expenses for each

        • Next Page