Kaizen #183 - COQL API's Enhancements in Zoho CRM API Version 7

Kaizen #183 - COQL API's Enhancements in Zoho CRM API Version 7

Hello everybody!

Welcome back to another post in our Kaizen series.
In this post, we will discuss the latest COQL API enhancements introduced in Zoho CRM Version 7.



COQL API

Query API lets you query for records based on queries using the CRM Object Query Language(COQL). COQL is based on the SQL query syntax, and supports the SELECT query to fetch records. Using this API, you can query for data across different modules that are linked using lookup fields. 

1. Enhanced Field Limits in the SELECT Clause

You can now retrieve up to 500 fields in a single query. Previously, the limit was 50. This allows you to fetch more data in a single request, reducing the number of API calls and improving performance.

Sample query:
{
  "select_query": "select Last_Name, Email, Phone, Industry, Revenue, ... (500 fields) from Leads where id is not null"
}

2. Enhanced Value Limits for IN and NOT IN Operators

The IN and NOT IN operators now support up to 100 values each, doubling the previous limit of 50. This enhancement allows for more comprehensive filtering in your queries. Users can now include a larger set of criteria in a single query, making it easier to retrieve your data without needing multiple queries.

Sample query for IN:
{
  "select_query": "select Account_Name from Accounts where Industry in ('IT', 'Finance', 'Healthcare', ... (100 values))"
}

Sample query for NOT IN:
{
  "select_query": "select Account_Name from Accounts where Industry not in ('IT', 'Finance', 'Healthcare', ... (100 values))"
}

3. Custom View support in COQL API

No more manual filtering! Simply use a custom view ID directly in the FROM clause. Retrieve custom view IDs using the Custom View API and include them in your queries to retrieve specific-custom view data.


Unsupported Custom Views
  • Custom View in Other Modules : The following custom views are not supported in any module.
    • Shared By Me
    • Co-owner
    • Shared To Me
In the Custom View API response for a module (e.g., Leads), search for the key "system_name". If the value matches any of the unsupported custom views (Shared By Me, Co-owner, Shared To Me), that view is not supported.

Example : Shared By Me

Key and Value Structure
 "system_name": "{module_name}SHAREDBYME" 
Example
"system_name": "LEADSSHAREDBYME"


COQL supports CVID in the following format: FROM {module_API_name}#{CVID}. 
See the sample query below for reference.

Sample query:
{
    "select_query": "select Lead_Status from Leads#5725767000000087501 WHERE id is not null"
}
//CVID: 5725767000000087501 - This is the Custom View ID in the Leads module.


4. Retrieve Corresponding Field Metadata via COQL

Need to retrieve field details? You can fetch both the required data and field metadata in a single query. Just add "include_meta" key to your query to retrieve field metadata. This key fetches metadata for the fields specified only in the SELECT column. Also, it eliminates making an additional GET - Fields Metadata API call to know the field metadata and save API credits.

Sample query:
{
    "select_query": "select Lead_Status, Phone from Leads where id is not null",
    "include_meta": [
        "fields"
    ]
}

Ensure you have the ZohoCRM.settings.fields.READ scope to avoid an OAUTH_SCOPE_MISMATCH error.

Sample Response:

{
    "data": [
        {
            "Lead_Status": "Attempted to Contact",
            "Phone": "555-555-5555",
            "id": "5725767000000420480"
        },
        {
            "Lead_Status": "Contact in Future",
            "Phone": "555-555-5555",
            "id": "5725767000000420481"
        },
        .
        .
        .
        
    ],
    "fields": {
        "Lead_Status": {
            "webhook": true,
            "operation_type": {
                "web_update": true,
                "api_create": true,
                "web_create": true,
                "api_update": true
            },
            "colour_code_enabled_by_system": false,
            "field_label": "Lead Status",
            "tooltip": null,
            "type": "used",
            "table_name": "CrmLeadDetails",
            "field_read_only": false,
            "required": false,
            "display_label": "Lead Status",
            "read_only": false,
            "association_details": null,
            "multi_module_lookup": {},
            "id": "5725767000000002611",
            "created_time": null,
            "filterable": true,
            "visible": true,
            "refer_from_field": null
             "auto_number": {}
        }
    },
    "info": {
        "count": 200,
        "more_records": true
    }
}


5. Field Limit Restriction in the ORDER BY Clause

The fields limit has been restricted in the ORDER BY clause. You can specify up to 10 fields in the ORDER BY clause for more precise sorting. Previously, there was no limit. This restriction helps improve query performance.

sample query:
{
    "select_query" : "select Last_Name from Leads where id is not null order by Lead_Source, Lead_Status, Email, ... (up to 10 fields)"
}

6. Duplicate fields restriction 

Duplicate fields are restricted in ORDER BY, GROUP BY, and AGGREGATE clauses. That is, if the same field is specified multiple times within the same clause, leading to unnecessary repetition and potential errors. This ensures cleaner and more accurate query results. Previously, this restriction applied only to the SELECT column. 

Bad query:
{
"select_query":"select id from Contacts where id is not null order by id,id"
}

Duplicate aggregate fields in a query will result in a "DUPLICATE_DATA" error in the response.

7. Retrieve territory information

You can now retrieve territory information from a module by including the territory field API name in the SELECT column. This is useful to understand where your data has been distributed in various geographical locations.

Sample query 1 :
{
  "select_query": "select Account_Name, Territories from Accounts where id is not null"
}

Sample query 2 :
{
 "select_query" : "select Territories, Account_Name.Territories from Contacts where id is not null" 
}

Sample response:

{
    "data": [
        {
            "Account_Name.Territories": [
                {
                    "name": "USA",
                    "id": "5725767000000454003"
                }
            ],
            "id": "5725767000000420261",
            "Territories": [
                {
                    "name": "China",
                    "id": "5725767000000454981"
                }
            ]
        },
        .
        .
        .
       
    ],
    "info": {
        "count": 174,
        "more_records": false
    }
}


Supported modules to retrieve territory details: Contacts, Accounts, Leads, and Deals.

Note: 
The territory field API names differ by module:
  • Accounts, Contacts, and Leads : Territories
  • Deals : Territory

8. "Full_Name" retrieval based on user preferences 

The full name can be retrieved based on the current user's display name pattern, as set in their preferences. This ensures that the full name format aligns with the user's settings.
The "Full_Name" field contains the concatenated values of the First_Name and Last_Name fields. This is a read-only field available only in the Leads and Contacts modules.

Sample query:
{
    "select_query": "select Full_Name from Contacts where id is not null"
}

9. Support for Multiple Modules in "what_id"

A Multi-Module Lookup (MML) field is a special type of lookup field that allows you to establish a relationship between a record in one module and records from multiple other modules. Unlike a standard lookup field that references a single module, an MML field can point to multiple module types.

Currently, an MML field is available in the Appointments module. The Appointment_For field is an MML field that can reference multiple modules, such as Leads and Contacts.

Sample query:
{
 "select_query": "select 'What_Id->Leads.Company','What_Id->Accounts.Account_Type' from Calls where id is not null"
}

9.1 Support to query Multi-module Lookup (MML)'s inner field

You can now retrieve inner fields of linked modules within the MML field. This provides deeper insights into related fields data in a module. 

For example, you can now query specific fields from a related module that is linked through a Multi-Module Lookup, making your data retrieval more precise and informative. 
{
 "select_query": "select 'Appointment_For->Contacts.Lead_Source' from Appointments__s where id is not null"
}
This query retrieves the Lead Source field from the Contacts module within the Appointment_For MML field. 

9.2 Support for Querying Multi-Module Lookup Module Name

Retrieve the module name associated with each record in a Multi-Module Lookup (MML) field. This helps in identifying the source module of the linked records, providing a better context for your data.

Sample query:
{
"select_query": "select Appointment_For.module.api_name, Appointment_For from Appointments__s where id is not null"
}
The Appointment_For.module.api_name returns the module name (e.g., Contacts or Accounts) for each record linked in the Appointment_For MML field.

10. Retrieving Consent-Related Information

You can now retrieve consent-related information using the Consents Lookup fields in a module. This is particularly useful for GDPR compliance, ensuring you have consent records.
For more details, refer to the Consent Management documentation. This is particularly useful for GDPR compliance, ensuring you have all necessary consent information.

Note:
  • Once GDPR is enabled and configured for a module, a new Data Processing Basis Details field will be created in the respective module with the data type consent_lookup ("data_type": "consent_lookup").
  • You can retrieve the Data Processing Basis Details field created in the module using the GET Fields Metadata API. 
  • To know all available fields in the Consents module, make another GET Fields Metadata API call.
Sample query:
{
"select_query": "select Data_Processing_Basis_Details.Contact_Through_Survey, Data_Processing_Basis_Details.Data_Processing_Basis from Leads where Data_Processing_Basis_Details is not null"
}

11. Enhanced Lookup Field Response 

Previously, when a lookup field was included in the SELECT column JOIN, only the lookup field’s ID was displayed. From V7, the corresponding display field value is also provided. Now, when you specify a lookup field in the SELECT column, the response includes the id of the Lookup record ID and the display field value of the lookup record. 

This eliminates the need for an additional SELECT column JOIN to fetch the display value (e.g., Owner.last_name).

Sample query:
{
"select_query" : "select Owner from Accounts where id is not null"
}


Sample response
                                               V6
                                      V7      
{
    "data": [
        {
            "Owner": {
                "id": "5725767000000411001"
            },
            "id": "5725767000000420169"
        },



        {
            "Owner": {
                "id": "5725767000000411001"
            },
            "id": "5725767000000420170"
        },
        .
        .
        .
    ],
    "info": {
        "count": 23,
        "more_records": false
    }
}
{
    "data": [
        {
            "Owner": {
                "name": "Boyle",
                "id": "5725767000000411001"
            },
            "id": "5725767000000420169"
        },


        {
            "Owner": {
                "name": "Kate",
                "id": "5725767000000411482"
            },
            "id": "5725767000000420170"
        },
        .
        .
        .
    ],
    "info": {
        "count": 23,
        "more_records": false
    }
}


Note:
  • If you query the Users lookup field in the SELECT column, the corresponding record’s last name (display field) will be displayed in the name key of the corresponding lookup JSON (e.g. Owner) response, from V7. 
  • Display field value will not be available for Consent Lookup and Multi-Module Lookup (MML) fields.

12. Increasing "Profile Image" field comparators

The Profile Image field now supports additional comparators.

                                                                         V6
                                    V7
      is null, is not null
 is null, is not null, =, !=, in, not in, like, not like

You can use a record image's ID to fetch related data. For example, if you only have a record image's ID and want to retrieve the respective record's last name, you can include the record image ID in your query. 
Refer to the COQL document for more details.

Sample query:
{
 "select_query" : "select Record_Image from Leads where Record_Image = 'siwz79472749456ff433f8b88d0a795ae9855' " 
}

13. Enhanced "Rollup Summary" field comparators

The Rollup Summary field now supports additional comparators, making it easier to filter and analyze your data with more precision.
                                                                                              V6                                                     V7
   is null, is not null
 =, !=, >=, >, <=, <, between, not between, in, not in, is null, is not null

Sample query:
{
 "select_query" : "select Last_Name from Leads where Total_Calls between 5 and 10"
}

13.1 Enhanced response for the Date and Datetime return types of the Rollup Summary 

The Date and Datetime return types in the Rollup Summary field are now provided in ISO date and ISO datetime formats based on the user's time zone.

Sample query:
{
"select_query": "select Last_Note_Added from Leads where id is not null"
}

Response
                                                 V6                                       V7
{
    "data": [
        
        {
            "Last_Note_Added": "1721302770000",
            "id": "5725767000003160016"
        },
        .
        .
        .
        
    ],
    "info": {
        "count": 200,
        "more_records": true
    }
}   

{    
"data": [
        
        {
             "Last_Note_Added": "2024-07-04T03:49:48-07:00",
            "id": "5725767000003160016"
        },
        .
        .
        .
        
    ],
    "info": {
        "count": 200,
        "more_records": true
    }
}    

14. Enhanced LIMIT and OFFSET Value Limit

You can now retrieve up to 100,000 records using pagination with the LIMIT and OFFSET clauses. This significantly increases the amount of data you can handle in a single query, making it easier to work with large datasets. Previously, the maximum limit was 10,000. For the next set of records, add another criteria id > {1,00,000th record ID} with the "AND" operator, and go on to fetch the next 1,00,000 records.

Sample query:
{
"select_query" : "select Last_Name, Created_Time from Leads where (Last_Name is not null and id > 5725767000003160016)"
}


15. Enhanced JOIN Support Limit

Base Column JOIN
If a query contains any lookup_field.{any_field} in any clause other than the SELECT column such as ORDER BY, GROUP BY, or AGGREGATE columns, then it will be treated as Base JOIN. The Base JOIN support limit has been increased from two to five. This enhancement enables more complex queries across multiple modules, improving data retrieval flexibility.

Sample query: 
{
 "select_query" : "select id from Contacts where id is not null order by Owner.role, Created_By.profile"
}

Refer to the Base JOIN section in the COQL API document for more details. 

15.1 Introducing the SELECT Column JOIN

A new SELECT column JOIN has been introduced, with a maximum limit of 15.

Advantages of SELECT Column JOIN
  • If a lookup field is included in the SELECT column and another lookup field is used in the Base column JOIN, they will be treated as separate JOINs. This ensures that the SELECT column JOIN does not affect the Base JOIN.
  • Previously, when two lookup fields in the SELECT pointed to the same module (e.g., Users), they were treated as separate JOINs. From V7, they are now considered a single JOIN, optimizing query performance and reducing redundancy.

Sample query:
{
"select_query" : "select Owner.last_name, Created_By.role from Contacts where id is not null"
}

Refer to the JOINs in COQL Queries for more details on both the JOINs.

16. Subquery in COQL

A subquery support has been given in COQL. A subquery is a child query that is nested or embedded within a parent query i.e., outer query. Subqueries can be used as an alternative to JOINs in a query. Use subqueries when a JOIN field is only needed in the criteria, i.e., in the WHERE clause. The primary reason for using subqueries is to improve performance by saving time and memory.  

Sample query:
{
"select_query" : "select Lead_Source,Email from Leads where Contacts in (select id from Contacts where Email='patricia@mail.com')"
}
You can retrieve up to 100 records per subquery in a single query. A maximum of 5 subqueries can be queried in a parent query. 
Refer to the Subquery documentation for more details. A detailed post on Subquery will be covered in an upcoming Kaizen post.


We trust that this post meets your needs and is helpful. Let us know your thoughts in the comment section or reach out to us at support@zohocrm.com.

Stay tuned for more insights in our upcoming Kaizen posts! 






    • Recent Topics

    • Has anyone successfully added Microsoft Graph API Oauth2 as a connection?

      I'm having trouble getting Microsoft Graph API created as a connection in zoho crm. Has anyone successfully added Microsoft Graph API Oauth2 as a connection? My issue is not necessarily on the Zoho side, but understanding how to set up the Microsoft side

    • Syncing Timesheets between Projects and Desk

      All users able to see their own timelog entries from all apps in one place, synced immediately. All managers able to view total/all time entries from one place. This is something that has come up for us and multiple clients. Example: we have a client

    • Spell Check default language

      Hello All, Is it possible to set the Spell Check default language? I can't find it in the settings. Thanks a lot! Levente

    • Zoho Backstage 3.0 - Boostez vos événements avec des outils malins

      Zoho Backstage vous accompagne dans l’organisation d’événements réussis, avec des outils qui simplifient la planification, optimisent l’exécution et renforcent la connexion avec votre public. La version 2.0 a apporté une nouvelle interface, plus de flexibilité

    • Portal user activity reporting

      Aside from the metrics section in the admin dashboard, is there a way to view/create reports for portal user activity? Im looking for a more granular option to see exactly what users are utilizing the portal. Thanks!

    • Automation #11 - Auto Update Custom Fields with Values from Emails

      This is a monthly series designed to help you get the best out of Desk. We take our cue from what's being discussed or asked about the most in our community. Then we find the right use cases that specifically highlight solutions, ideas and tips to optimize

    • Admins to set Agents Picture

      Admins should not have to rely on agents to set a nice profile picture for them. Admins get the headshot pictures from HR and should be able to upload and set their picture, not rely on them to: 1) upload a picture at all 2) upload a good picture 3) upload

    • Time Tracking Reporting and Billing

      I wish for the time tracking module to be enhanced further. Currently it is independent of Support Plans and Contracts. Support Plans and Contracts are also mostly separate. We need a better dashboard of this with the ability to natively mark billed or

    • Enhanced Email Signature Folding

      We have departmental signatures setup which are great, however, when viewing ticket details, it gets very overwhelming when scrolling though threads and conversations where you scroll past ten different signatures of your own team, then ten signatures

    • How to add formatting in zoho.cliq.postToUser(...) message?

      In a CRM Deluge function, I'm trying to use the message formatting guidelines given here: https://www.zoho.com/deluge/help/cliq/posting-to-zoho-cliq.html#message-formats My message is: message: #Title text. The result in Cliq is: #Title text. (no large

    • How to add line breaks in zoho.cliq.postToUser(...) message?

      In a CRM function using Deluge I'm sending this message and attempting to add some line breaks but they are ignored. Is there another way to add these breaks? My message: message: New urgent task\nDescription \nThis is a fake description.\n A new line?

    • Zia Agents/End of Day Reports

      As a manager or owner it would be nice if Zia analyzed today's (or this week's tickets) and gave an end of the day report to management team. - what important tickets were worked on or submitted today? - what agents were unproductive today and answered

    • Project Cost Tracking

      I see there are questions/concerns that Zoho doesn't track costs to a tasks in a project. We are a manufacturer and are in the early stages of tracking costs to project. I would like to expand out the COGS Chart of accounts in Books and record costs via

    • How to record if the payment made is return due to transaction failed.

      So there is Bill of $2000, and a payments made transaction to clear the bill. The amount is actually deducted from bank account. However, a few days later, I found the bank returned only $1750 cause there are $250 bank service charge for this failed transaction.

    • Help Center Customization UI

      The customization screens for the help center needs the UI improved. It looks straight out of 2004. The Zoho Desk normal UI is great. All it takes is uniform fonts and colors across all parts of the tool... I compare this to Zendesk Guide.

    • Este domínio já está associado a esta conta

      Fui fazer meu cadastro na zoho e quando digitei meu domínio recebi essa mensagem que meu domínio estava associado a uma conta que eu nem faço idéia de quem seja. Como que faço pra resolver isso? Atenciosamente, Anderson Souza.

    • I need some help in Expenses Per Diem Policy

      this is my script written for restricting the PerDiem Components. Say if Lodging and Per Day Allowance both is selected from Per Diem Page then the report should gets auto rejected. When Im trying to executing it says the following error {"code":11,"message":"The

    • Adding Photos to Dashboards on Zoho Analytics

      I am creating a dashboard to showcase data from survey results from focus groups. I am creating a focus group participant profile tab where it is filtered by the name of the participant and showcases information about them using KPI widgets. I am running

    • What is the difference between Retainer invoice and Advance Payments?

      Retainer invoice seem like they are just advance payments with extra details. Instead of creating a Sales Order with order details, a retainer is created. It feels like they are a workaround to link advance payments with sales orders. Is there any advantage

    • Exporting record notes in bulk

      Hi team, Is it possible to bulk export the notes attached to a record? i.e to a CSV file or otherwise. Our use case is exporting all notes for our lead/account/Deal records. We have another system we'd like to import these notes to but I can't seem to

    • Field customization

      Hi Team Good day! I am a commission agent who sell and purchase goods from vendors, while in purchasing invoices I am not able to deduct the expenses such as commission and other expenses on actual amount. Kindly help me to customize the invoice based

    • vendors / customers with 2 different address and gst no

      Why can't we have option for more than one address and depending on the state option for more than 1 GST no. ? We have customers / vendors PAN india with different addresses and GST no. for different states.

    • Error: Invalid Element gst_no, Invalid Element gst_treatment, Invalid Element place_of_contact

      so i am creating a new contact post request and i want add gst infomation when amount is above 50000 and if pass gst info in request body then i get this errors > Error: Invalid Element gst_no, Invalid Element gst_treatment, Invalid Element place_of_contact

    • Add multiple Billing Addresses under one GST number

      My client owns multiple businesses in various locations but they all come under one GST. Is there a way to add multiple billing addresses for the same GST? Managing this by adding multiple Shipping addresses is not an option. The client wants the GST

    • Zoho Mail API - Upload Attachment

      https://www.zoho.com/mail/help/api/post-upload-attachments.html I followed the steps from the API documentation and wrote a backend in JavaScript to send emails. Normal emails are sent without any problems. However, I can’t send emails with attachments.

    • Unable to create custom fields for shipment order

      I'm unable to create custom fields for shipment orders, even though the custom fields are set up correctly. A request to the following endpoint: https://www.zohoapis.com/inventory/v1/settings/preferences/customfields?organization_id=${ZOHO_ORGANIZATION_ID}&entity=shipment_order

    • Kaizen #202 - Answering Your Questions | Testing and Using REST APIs in Widgets

      Hello Developers! Welcome back to a fresh week of Kaizen! Thank you for your active participation in sharing feedback and queries for the 200th milestone. This week, we will look at the following queries related to widget: Widget Testing Using REST API

    • Introducing the 'Send as Email' option on the Zoho Desk iOS mobile app

      Hello everyone! In the latest version(v2.10.2) of the Zoho Desk iOS app, we have brought in support for the 'Send as Email' option while creating a ticket. This feature enables you to reach out to the customers by sending outbound emails. The emails are

    • Zoho Forms Not Loading on Website – DNS Resolution Error

      Dear Zoho Support Team, User ID : 20069458731 We are experiencing an issue with the Zoho Form embedded on our website (https://vitel.com.tr/satis-destek-formu/). The form is not loading, and the following error message appears in the browser: “forms.zohopublic.eu

    • Data backup retention question/

      My zohocrm subscription gives me 2 full data backups per month. I have a scheduled backup configured to run twice a month. I just went to download my backup and i can't find it, it ran about 9 days ago... From what i can tell with google zoho only keeps

    • Basic Apple Watch App

      Sometimes I leave my phone behind. I will get push notifications that tickets are updated etc.. It would be nice to at least view them and do a few basic functions. reassign. public reply. private comment.

    • Look and Feel Uniformity

      Someone needs to go through the mobile app and match the look and feel of the web version. For example, it is global standard to highlight private notes as yellow background hue. Desk does that on web, but not on mobile. Mobile also has an odd blue icon

    • Managing two books in Zoho Books

      is it possible to effectively manage two separate books within Zoho Books? My organization is considering handling accounting for two distinct subsidiaries, and we would like to understand the best way to achieve this within the Zoho Books.

    • Display All Custom Buttons Without Dropdown on Record Page

      In my org's workflow we usually want to do some kind of quick action off of an individual record - i.e. of an individual contact, or individual deal. What we have always found a hindrance is the location of all custom buttons being in the drop down on

    • Zoho Sales Team - Extremely Slow Response Times

      Hi everyone, Has anyone else experienced unusually slow response times from Zoho’s sales team? I sent an email last night, and it’s been nearly 24 hours with no reply. While I understand delays can happen, this seems longer than expected for a sales inquiry.

    • Yodlee Bank Feeds

      I'm well aware of the many bank feed issues out there that haven't been resolved, but I'm looking for information on Rules in relation to bank feeds. U.S based, Bank of America user and prior to Yodlee all of my banking feeds and Rules worked seamlessly.

    • Unable to create custom function

      Unable to create custom function - Please check the screenshot for the details HERE IS THE FUNCTION!! try { // 1. Fetch the details of the approved Bill using its ID billDetails = zoho.books.getRecordById("Bills", organization.get("organization_id"),

    • Need a feature which can validate PAN from Income Tax Portal

      Hello Zoho, We need a feature which can help us validate PAN which is being entered in AR/AP Profiles to check if it is valid and display the name as per Income Tax so as to get rid of incorrect PAN into the systems. Please do the needful Thanks

    • PAN - Aadhar Link Status

      Can Zohobooks also get latest PAN-Aadhar Linking Status from Income Tax Portal ?

    • Canvas translation

      We want to offer our CRM system to our users in English and Dutch. However, it seems that text in our deal Canvas isn't available for translation through the translation file. The same applies to the field tooltips. They don't appear in the translation

    • Next Page