Kaizen #171: FAQs on COQL API

Kaizen #171: FAQs on COQL API

Hello all!!
Welcome back to another post in the Kaizen series!

In this post, we will address some of the most frequently asked questions about Zoho CRM's COQL API from the Zoho CRM Developer Community Forum.




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. Why did I get a SYNTAX error for the following query?


{
    "select_query":"select External from Contacts where id is not null"
}


Answer: 
The error occurs because the query uses an SQL reserved keyword, "External", as a column name without enclosing it in quotes. When using SQL reserved keywords like "External", you must enclose them in single or double quotes.

The above-query can be written as:

{
    "select_query":"select 'External' from Contacts where id is not null"
}



------------------------------------------------------------------------------------------------------------------------------------

2. Why does the following query throw an error?


{
    "select_query":"select id from Contacts where id is not null and Account_Name is not null and Vendor_Name is not null"
}


Answer: 
When the query involves more than two criteria, ensure that you enclose your criteria properly by grouping them in pairs, such as ((A and B) and C).

The above-query can be written as:

{
    "select_query": "select id from Contacts where ((id is not null and Account_Name is not null) and Vendor_Name is not null)"
}


------------------------------------------------------------------------------------------------------------------------------------

3. How to escape single quotes within single quotes and double quotes within double quotes?

Answer: 
For single quote:

If you want to retrieve a value that contains a single quote, for example, 1' 2 in the Designation field (a single-line field), you need to escape the single quote in the value by adding another single quote.

Example:
1'' 2

Sample Input and Response:



For double quotes:

If you want to retrieve a value which contains double quotes, for example, 1' ' 2 in the Designation field (any single-line field), then you have to escape each double quotes with backslash (\) in the value.



------------------------------------------------------------------------------------------------------------------------------------

4. Why does the following query throw an error?


{
    "select_query":"select What_Id->Leads.Last_Name from Tasks where id is not null"
}


Answer: 
Special characters such as "-",  ">"  "*", and "!" in a query must be enclosed within quotes, either in single or double quotes. 
Your query can be written as:


{
    "select_query":"select 'What_Id->Leads.Last_Name' from Tasks where id is not null"
}



------------------------------------------------------------------------------------------------------------------------------------

5. How can I retrieve records from a subform module using COQL?

Answer: 
To retrieve subform data within a module, specify the respective subform module's API name in your query instead of querying the parent module. For more details, refer to Kaizen #124 on managing Subforms using Zoho CRM APIs.

------------------------------------------------------------------------------------------------------------------------------------

6. How to retrieve Multi Select lookup field data using COQL?

Answer: 
To query Multi-Select Lookup fields (MxN fields), you need to retrieve the data through the corresponding linking module instead of querying them directly from the parent module. For more details, refer to Kaizen #125 on manipulating Multi-Select Lookup fields using Zoho CRM APIs.

------------------------------------------------------------------------------------------------------------------------------------

7. Can I query more than 50,000 records?

Answer: 
Up to V6, you can retrieve up to 10,000 records without changing the criteria by using the LIMIT and OFFSET in your query. When retrieving the initial 10,000 records, make an API call with Created_Time, Modified_Time, or ID in the ORDER BY clause. To fetch more than 10,000 records, apply a condition based on the fields used in the initial ORDER BY clause in the query.
Refer to the Pagination section for more details. 
From V7 onwards, we support retrieving up to 1,00,000 records without changing the criteria by using LIMIT and OFFSET in your query. To fetch more than 1,00,000 records, please refer to the Pagination section for more details.

------------------------------------------------------------------------------------------------------------------------------------

8. Is territory field supported in COQL?

Answer: 
Yes,  you can use the territory field in the COQL from V7. Refer to the Territories section in COQL document for sample.
------------------------------------------------------------------------------------------------------------------------------------

9. Is CVID support provided in COQL?

Answer: 
Yes, from V7, you can use the CVID in your query. Refer to the CVID section in the COQL document for details.
------------------------------------------------------------------------------------------------------------------------------------

10. What are the supported aggregate functions, and why do they not work with values like Avg or avg?

Answer:
The aggregate functions are case-sensitive and only work when specified in all capital letters.  Using values like Avg or avg will result in an error.
The supported aggregate functions are MIN, MAX, AVG, SUM, and COUNT. 

------------------------------------------------------------------------------------------------------------------------------------

11. Are other SQL-related functions like CONCAT or DATE() supported in COQL?

Answer:
No, COQL in Zoho CRM API Version 7 currently supports only aggregate functions and does not include other SQL-related functions like CONCAT or DATE().
------------------------------------------------------------------------------------------------------------------------------------
12. Is it possible to select more than 50 fields in the SELECT column?

Answer:
Yes, from Zoho CRM API Version 7, the limit has been increased from 50 to 500 fields in the SELECT column.
------------------------------------------------------------------------------------------------------------------------------------

13. Can Multi-Module Lookup inner fields be queried?

Answer:

Yes, you can query fields from the associated module in a Multi-Module Lookup (e.g., Appointments module). 

Use the following format:

select 'What_Id->{associated_module_API_name}.{field_API_name_from_associated_module}'

Example:

{
  "select_query": "select 'What_Id->Leads.Last_Name','What_Id->Accounts.Account_Type' from Events where id is not null"
}



Note:
From Zoho CRM API Version 7, you can also query the "Appointment_For" field.

------------------------------------------------------------------------------------------------------------------------------------

14. Is Display Name available for all types of lookup fields?

Answer:
From V7, the display name is available for Lookup and User Lookup fields when you specify them in the SELECT column, but it is not available for Consent Lookup and Multi-Module Lookup (MML) fields.
Please note, for the Users module, only the "last_name" is shown as the display field for the Users module is last_name.

Example:

{
    "select_query": "select Account_Name, Owner, Data_Processing_Basis_Details from Contacts where Data_Processing_Basis_Details is not null"
}


Response:

{
    "data": [
        {
            "Owner": { //user lookup field
                "name": "Boyle",
                "id": "5725767000000411001"
            },
            "Account_Name": { //lookup field
                "name": "Zoho",
                "id": "5725767000003464060"
            },
            "Data_Processing_Basis_Details": { //consent lookup field
                "id": "5725767000005083039"
            },
            "id": "5725767000005091053"
        }
    ],
    "info": {
        "count": 1,
        "more_records": false
    }
}


------------------------------------------------------------------------------------------------------------------------------------

15. Is it possible to get a Full Name based on User Preference?

Answer:
The Full Name field is supported in the Leads, Contacts, and Users modules.

Leads and Contacts modules:
  • Below V7: You must query the first_name and last_name fields separately and concatenate them to form the Full Name.
  • From V7: You can directly query the full_name field in the SELECT column, and it will return data based on the User Preference.
Users module:
In all versions, the full_name field is not directly supported. You need to query the first_name and last_name fields separately and concatenate them to construct the Full Name.

------------------------------------------------------------------------------------------------------------------------------------

16. Is it possible to use Profile Image and Rollup Summary fields in criteria?

Answer:
From V7, you can use Profile Image and Rollup Summary fields in criteria.

------------------------------------------------------------------------------------------------------------------------------------

17. Which fields are restricted in all clauses?

Answer:
The following fields are restricted from being included in all columns:
  • Multi-select lookup fields: These cannot be queried directly from the parent module. Instead, query them from their respective linking modules.
  • Line items: Pricing_Details and Product_Details
    • Pricing_Details: This field cannot be queried as it is not a subform but a separate section.
    • Product_Details: This is a subform. You cannot query data from the parent module. Instead, query it directly from the respective subform module.
  • Participants in the Events module.
  • File/Image upload fields
  • Availability Information fields in the Services module
    • Choose Date(s)
    • Choose Day(s)
Check the following image for reference.



------------------------------------------------------------------------------------------------------------------------------------

18. Which fields are restricted only in criteria?

Answer:
The following fields have restrictions when used in criteria:
  • Multiline fields: Cannot be used in criteria.
  • Encrypted numeric fields: Support limited comparators (is null, is not null, =, != ).
  • Encrypted non-numeric fields: Support only is null and is not null comparators.
------------------------------------------------------------------------------------------------------------------------------------

19. Which fields are restricted only in the Group By clause?

Answer:
Encrypted fields are restricted from being used in the Group By clause.

------------------------------------------------------------------------------------------------------------------------------------

20. Which fields are restricted only in the ORDER BY clause?

Answer:
Encrypted fields are restricted from being used in the ORDER BY clause.

------------------------------------------------------------------------------------------------------------------------------------

21. Is External ID supported in COQL?

Answer:
Yes, External ID has been supported from Zoho CRM API's Version 4. Please note that operators such as "is null" and "is not null" are not supported in the criteria when using External ID.

Supported operators are "=", "!=", "in" and "not in".

------------------------------------------------------------------------------------------------------------------------------------

22. How to resolve a 408 error (Request Timeout)?

Answer:
If your query takes more than a second to parse, a request timeout error will occur.

To avoid this, ensure the query is not overly complex and that all parentheses are properly balanced. Simplifying the query or fixing any mismatched parentheses can help resolve the issue.

------------------------------------------------------------------------------------------------------------------------------------

23. Is it necessary to query the records based only on the User Time Zone?

Answer: 
No, users can query records based on any time zone. However, the response will always be returned in the time zone of the user who made the query.

------------------------------------------------------------------------------------------------------------------------------------

24. Which fields are restricted when using aggregate functions, for example, SUM(field_API_name)?

Answer: 
Encrypted fields are restricted and cannot be used in the aggregate functions like SUM, AVG, MIX, or MAX.

------------------------------------------------------------------------------------------------------------------------------------

25. Where can we use Alias?

Answer:
Alias can be used in the SELECT clause and in the ORDER BY clause. You can assign an alias in the SELECT clause, and the assigned alias can be referenced in the ORDER BY clause. But you cannot assign an alias directly in the ORDER BY clause. 

Note: Alias cannot be used in the other clauses, such as WHERE and GROUP BY.

------------------------------------------------------------------------------------------------------------------------------------
Info
More enhancements in the COQL API are now live in Zoho CRM API Version 7. Check out the V7 Changelog for detailed information on these updates.

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

    • Sticky Posts

    • Kaizen #198: Using Client Script for Custom Validation in Blueprint

      Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

    • Kaizen #226: Using ZRC in Client Script

      Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In this

    • Kaizen #222 - Client Script Support for Notes Related List

      Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore how

    • Kaizen #217 - Actions APIs : Tasks

      Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.

    • Kaizen #216 - Actions APIs : Email Notifications

      Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are

    • Recent Topics

    • RSC Connectivity Linkedin Recruiter RPS

      It seems there's a bit of a push from Linkedin Talent Solutions to keep integrations moving. My Account Manager confirmed that Zoho Recruit is a Certified Linkedin Linkedin Partner but does not have RSC as of yet., (we knew that :-) She encouraged me

    • im facing issue on generate the Estimate price

      i couldn't understand what is the issue , i cant generate Estimate price where is the issue

    • cannot be able to add user

      Dear team I tried to add a new user for sales team, but after entering the OTP its showing error message cannot add now

    • Changing an existing item to different accounts & inventory-tracked

      Hi everyone, I have an item in Zoho Books that was originally set up as a non-inventory item. Over time, I associated it with different sales and purchase accounts, and I now have many invoices, bills, and reports that use this item. My business process

    • How do I edit the Calendar Invite notifications for Interviews in Recruit?

      I'm setting up the Zoho Recruit Interview Calendar system but there's some notifications I don't have any control over. I've turned off all Workflows and Automations related to the Calendar Scheduling and it seems that it's the notification that is sent

    • Bookings duration - days

      Hi team, Is there any way to setup services/bookings that span multiple days? I am using Zoho Bookings for meeting room bookings. Clients may wish to book a room for more than one day, for up to a month.  If not, is there a plan to allow services to be setup with durations of Days as well as hours and minutes? Many thanks, Anna.

    • big 5 accounts

      how do you find what accounts are listed as Big 5 ?

    • Zoho recruit's blueprint configuration is not functioning as mapped

      Current Status: Zoho Blueprint is not functioning as configured. Issue: We are moving a Candidate status in Zoho Recruit "for active file" but we encountered: "Status cannot be changed for records involved in Blueprint." This happens to various client

    • Actual vs Minimum

      Hi all, I am sure I am not the only one having this need. We are implementing billing on a 30-minute increment, with a minimum of 30 minutes per ticket. My question is, is there a way to create a formula or function to track both the minimum bill vs the

    • Delay in rendering Zoho Recruit - Careers in the ZappyWorks

      I click on the Careers link (https://zappyworks.zohorecruit.com/jobs/Careers) on the ZappyWorks website expecting to see the job openings. The site redirects me to Zoho Recruit, but after the redirect, the page just stays blank for several seconds. I'm

    • How to add interviews through API

      I'm trying to add an interview without much luck. The documentation gives examples of adding just about everything except an interview. However, the issue might be the way I'm formatting it, because the documentation is unclear to me. It seems as if the xml should be passed in the url, which seems unusual. I've tried the data as both plain and character escaped, but nothing seems to work, nor do I even get an error response. https://recruit.zoho.com/recruit/private/xml/Interviews/addRecords?authtoken=***&scope=recruitapi&version=2&xmlData=<Interviews> <row

    • Can't scroll the page down unless I refresh the page

      Hello, This issue has been going on with me and a lot of other users in my organization, we can't scroll down! the scrolling side bar doesn't appear and scrolling down through mouse or keyboard keys doesn't work, it seems that the page just ends in the

    • Offer already made- but I withdrew it

      I made an offer letter, but made a mistake on it. I withdrew the offer but now I can't recreate the correct offer. Zoho keeps saying that "A same offer has already been made". I look in the "offers" and there are NO offers (this is the first time I've

    • Control the precision of answer bot responses

      Hello everyone, Admins can control the precision with which the Answer bot analyzes and generates a response by adjusting the threshold levels. Based on predefined threshold values, Zia analyzes how closely the query matches with the available KB articles.

    • Rebrand your CRM with the all-new custom domain mapping setup

      UPDATES TO THIS FEATURE! 19th Jan, 2024 — Custom domain mapping has been made available for portal users in Zoho One and CRM Plus. 23rd June, 2023 — Custom domain mapping has been made available for all users, in all DCs. Hello everyone! We are elated

    • Add Israel & Jewish Holidays to Zoho People Holidays Gallery

      Greetings, We hope you are doing well. We are writing to request an enhancement to the Holidays Gallery in Zoho People. Currently, there are several holidays available, but none for Israel and none for Jewish holidays (which are not necessarily the same

    • Sender Email ID is duplicate

      My sender id "automate@erplaunchpad.com" is coming as duplicate but I have not used it anywhere else please help

    • CRM x WorkDrive: File storage for new CRM signups is now powered by WorkDrive

      Availability Editions: All DCs: All Release plan: Released for new signups in all DCs. It will be enabled for existing users in a phased manner in the upcoming months. Help documentation: Documents in Zoho CRM Manage folders in Documents tab Manage files

    • Building Toppings #6 - Install and uninstall actions

      Hello Biginners! In our previous forum post, we explored creating connections - specifically, custom service connections in the Bigin Developer Console. In this post, we'll focus on another feature that can be used in every topping: install actions. We'll

    • New UI in Zoho One CRM

      Hello, Just switched to the new UI for Zoho One CRM, do not like it, especially the search functions. What are the steps to backstep to the previous UI? UPDATE: I found it.

    • App like Miro

      Hi all, is there a way to have a interactive whiteboard like in Miro? We want to visualize our processes and workflows in an easy way.

    • Important updates to your connectors

      Hello everyone, Greeting from Zoho Creator! We're excited to announce that we'll be rolling out significant backend updates to Zoho Creator's built-in connectors to enhance security by following the latest frameworks. The existing version of some of the

    • Product Request: Send email to Secondary email

      Guys, we should be able to send the campaign to the secondary email too.  Is this on the plans for Zoho Campaign? It looks like I can map the secondary email from the CRM to the Campaigs, but can not send the message.  

    • Logic for sending to a non-primary email address

      Hi, I have a scenario where contacts are able to sign up for emails with 2 different email addresses (example: work, personal). I've mapped both to Campaigns from Zoho CRM, but when I go to target an email only the primary email addresses are pulling in. How can I update this to look at both of the email addresses - or specifically the secondary email address in Campaigns? Thanks, Jenny

    • How Do Mutliple Sales People Prospect in the "LEADS" module without calling the same leads?

      We have 4 sales reps and the Leads module does not have real time intuitive knowlodge to make the sales rteps dont call the same people at the same time. How can we crate a fluent prospecting sytem where the salres reps can go out bound without calling

    • Keeping track of project expenses

      I have talked to a few support techs and it is very hard for me to believe that Zoho's project accounting software can't keep accounts for my projects. I must not understand what they're saying. We get a contract to build something. So the project revenue

    • Mailbox delegation - A secure way to enable collaboration

      Admins often encounter scenarios where a user needs another team member to access and manage their mailbox during extended leave, role transitions, or while handling high email volumes. In such situations, ensuring business continuity without sharing

    • Canvas View bug

      I would like to report a bug. When clone a canvas view from an existing canvas view, if the original canvas view have canvas button with client script. Then the new create canvas view will have canvas button, it is make sense. But when I try to delete

    • Export blueprint as a high-resolution PDF or image file

      This would be a good feature for organizations that want to share the blueprint process with their employees but don't want them to have access to the blueprint in the system settings. At the moment all that users can do is screenshot the blueprint or

    • Zoho Recruit Community Meetup - London 🇬🇧 (Venue Finalised)

      Hello Recruiters! We’re excited to announce that the Zoho Recruit team is coming to the UK for an in-person Zoho User Group (ZUG) Meetup in London! This is your chance to connect with fellow Zoho users, learn from experts, and walk away with actionable

    • Users may not pick the fields to be shown as columns in the Choose Account window when creating a new Deal record

      Hi there, by talking with other users I found out that I, as an Admin, am the only one who can pick fields to be shown as columns in the Choose Account window when creating a new Deal record. In fact, if other users click on the "Add Column" symbol on

    • 【参加無料】東京 Zoho ユーザ交流会 NEXUS ー AI エージェント (Zia Agents)の活用事例 / CRMで実現するマーケティング業務効率化

      ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 3月27日(金)に東京、新橋で「東京 Zoho ユーザー交流会 NEXUS」を開催します！ ーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーー ✒️申し込みはこちらから：https://www.zohomeetups.com/tokyo2026vol1#/?affl=communityforumpost2 ーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーー ★参加のおすすめポイント ✅ AIエージェント（Zia）のリアルに使える実例を知る

    • One Support Email Managed By Multiple Departments

      Hello,  We use one support email (support@company.com). Incoming emails come to the "Support Department" and based on what the customer is asking, we route that ticket to different departments (billing, technical support, etc.). When users in these different

    • Error AS101 when adding new email alias

      Hi, I am trying to add apple@(mydomain).com The error AS101 is shown while I try to add the alias.

    • ZOHO.CRM.UI.Record.open not working properly

      I have a Zoho CRM Widget and in it I have a block where it will open the blocks Meeting like below block.addEventListener("click", () => { ZOHO.CRM.UI.Record.open({ Entity: "Events", RecordID: meeting.id }).catch(err => { console.error("Open record failed:",

    • Python - code studio

      Hi, I see the code studio is "coming soon". We have some files that will require some more complex transformation, is this feature far off? It appears to have been released in Zoho Analytics already

    • 🚀 WorkDrive 6.0 (Phase 1): Empowering Teams with Content Intelligence, Automation, Accessibility, and Control

      Hello, everyone! WorkDrive continues to evolve from a robust file management solution into an intelligent, secure, and connected content collaboration platform for modern businesses. Our goal remains unchanged: to simplify teamwork, strengthen data security,

    • Introducing Workqueue: your all-in-one view to manage daily work

      Hello all, We’re excited to introduce a major productivity boost to your CRM experience: Workqueue, a dynamic, all-in-one workspace that brings every important sales activity, approval, and follow-up right to your fingertips. What is Workqueue? Sales

    • Support Custom Background in Zoho Cliq Video Calls and Meetings

      Hello Zoho Cliq Team, We hope you are doing well. We would like to request an enhancement to the video background capabilities in Zoho Cliq, specifically the ability to upload and use custom backgrounds. Current Limitation At present, Zoho Cliq allows

    • Upload own Background Image and set Camera to 16:9

      Hi, in all known online meeting tools, I can set up a background image reflecting our corporate design. This doesn't work in Cliq. Additionally, Cliq detects our cameras as 4:3, showing black bars on the right and left sides during the meeting. Where

    • Next Page