Kaizen #183 - COQL API's Enhancements in Zoho CRM API Version 7
Hello everybody!
Welcome back to another post in our Kaizen series.
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
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" } |
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.
{ "select_query": "select Appointment_For.module.api_name, Appointment_For from Appointments__s where id is not null" } |
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!
Topic Participants
Subramanian K
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 thisKaizen #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 howKaizen #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
Sendpulse SMTP/IMAP Issues
It’s possible Zoho made some changes on their side. Sometimes, even if your regular password works, Zoho requires an app-specific password for external apps like SendPulse to connect via IMAP. You can create this in Zoho’s security settings and use itInsane mail security
I cannot access my email... anywhere. For some reason the password for the Mail app on my Mac is being rejected, it worked yesterday but now it doesn't? Ok let's try the web interface. I can access my general Zoho login with the password but if I wantUI issue with Organize Tabs
When looking at the organize Tabs window (bellow) you can see that some tabs are grayed out. there is also a "Add Module/Web Tab" button. When looking at this screen it's clear that the grayed out tabs can not be removed from the portal user's screenTask list flag Internal/External for all phases
Phases are commonly used in projects to note milestones in the progression of a project, while task lists can be used to group different types of tasks together. It makes sense to be able to define a task list as either internal or external however theHAVING PROBLEM WITH SENDING EMAIL
Hi all, I'm unable to receive emails on info@germanforgirls.eu. I'm getting an error code 550. 5.1.1. invalid email recipients. Moreso, I would like info@germanforgirls.eu to be the default "send from" email and not solomon@germanforgirls.eu. Kindly seeSharing my portal URL with clients outside the project
Hi I need help making my project public for anyone to check on my task. I'm a freelance artist and I use trello to keep track on my client's projects however I wanted to do an upgrade. Went on here and so far I'm loving it. However, I'm having an issue sharing my url to those to see progress. They said they needed an account to access my project. How do I fix this? Without them needing an account.Different Task Layouts for Subtasks
I was wondering how it would be possible for a subtask to have a different task layout to the parent task.Subscription went to default (@zoho.com) address instead for custom domain
Hello! So I bought a lite sub to test things out, wanting to use my own domain. However, after passing through all the verification steps (completed now), it seems that the sub I bought was assigned to the default email that I already had with Zoho andCanvas templates and font-family
i dont understant why its always the smallest things that waste all of my time! why in some videos i see they have tamplates in the Canvas editor and i cant seem to fint it? and why oih why cant i cange the font? i just want simple Arial! help meeeeeeeeeeRe: Ca.gory groups and not all email addresses being added to a group emails
Hi, I have added emails under 'Contacts' into categories but when sending a group email and putting the category name in not all email addresses go onto the email. I have refreshed the page, deleted and redone the info etc with no luck. I only found outIMPORTANT
Dear Zoho Support Team, I am currently experiencing an issue when trying to send emails from my Zoho Mail account. Each time I attempt to send a message, I receive the following error: "Unable to send message; Reason: 554 5.1.8 Email Outgoing Blocked."Able to Send Emails from Zoho but Not Receiving Emails from Gmail
Hello, I am experiencing an issue with my shopify domain email setup and would appreciate your help. Current situation: I can successfully send emails using Zoho. I can receive emails from some services (for example, Facebook). However, I cannot receiveAntispam validation failed for your domain in Accounts
I tried adding a domain to zeptomail.zoho.com, but the “add domain” operation failed. The front‑end error reads: “Domain could not be added. Please contact support@zeptomail.com.” The back‑end API returned: ``` { "error": { "code": "TM_3601", "details":Announcing new features in Trident for Windows (v.1.38.5.0)
Hello Community! Trident for Windows just received a major update, with a range of capabilities that focuses on strengthening and enhancing communication. Let’s dive into what’s new! View complete technical email details. For those who need deeper visibilityWindows Desktop App - request to add minimization/startup options
Support Team, Can you submit the following request to your development team? Here is what would be optimal in my opinion from UX perspective: 1) In the "Application Menu", add a menu item to Exit the app, as well as an alt-key shortcut for these menusAccounting of Amazon
I have recently started selling on Amazon.in and I am facing issues with different types of transactions: What entry to do in case of return? If I had sent two products and customer returned both the products but I had received only one and got the claimCompose Emails Faster Using Templates and Snippet
Hello everyone, We have made an enhancement to the Send as Email option in Tickets. Agents can use templates and snippets to draft their response, which helps save time and maintain consistency. The Send as Email page will display the available templatesCustomize Colors used on graphs and charts according to users desire.
It would be great if we could customize the graph's colors as we see fit. I hate that yellow is always the default color!Emails not integrating
My emails from Hubspot did not integrtate over. How do I fix that?Creating meetings from an email
Hi. Similar to Outlook, it would be helpful if a meeting can be scheduled from an email so that the attendees need not be manually entered every time it's created.Zoho Social API for generating draft posts from a third-party app ?
Hello everyone, I hope you are all well. I have a question regarding Zoho Social. I am developing an application that generates social media posts, and I would like to be able to incorporate a feature that allows saving these posts as drafts in Zoho Social.CRM Percent custom fields: When will it show the % symbol and behave like %?
1. Actually Percent custom fields fail to show the % symbol. 2. When in formulas Percent fields work like number: 100 x 5% = 5 ideal world 100 x 5% = 500 what happens actually 3. When importing Percent fields the % symbol has to be removed and the dataDeprecation of the Zoho OAuth connector
Hello everyone, At Zoho, we continuously evaluate our integrations to ensure they meet the highest standards of security, reliability, and compliance. As part of these ongoing efforts, we've made the decision to deprecate the Zoho OAuth default connectorRouteIQ for Zoho FSM
Beste, Zou wel top zijn dat we een RouteIQ hebben voor FSM aangezien we constant moeten zien wat de beste route is voor onze monteurs. Nu moeten we een speciale aparte programma hebben om de beste route te berrekenen voor onze monteurs aangezien de planningLet us view and export the full price books data from CRM
I quote out of CRM, some of my clients have specialised pricing for specific products - therefore we use Price Books to manage these special prices. I can only see the breakdown of the products listed in the price book and the specialised pricing forChanges to the send mail Deluge task in Zoho CRM
Hello everyone, At Zoho, we continuously enhance our security measures to ensure a safer experience for all users. As part of our ongoing security enhancements, we're making an important update on using the send mail Deluge task in Zoho CRM. What's changing?How to Invoice Based on Timesheet Hours Logged on a Zoho FSM Work Order
Hi everyone, We’re working on optimizing our invoicing process in Zoho FSM, and we’ve run into a bit of a roadblock. Here’s our goal: We want to invoice based on the actual number of hours logged by our technicians on a job, specifically using the timesheetsInclusion is the new engagement
When in a very challenging situation, you may have peers or friends around you saying, “Everything will be okay.” They speak to you in a way that they are connected or in a language or tone that feels close. But your inner voice comes to you in a trulyDKIM verification for Squarespace website - Corrections to instructions
Zoho Campaigns DKIM TXT record instructions for Squarespace show that Host field should show: 22111._domainkey.[domain name, e.g. mywebsite.com] However, after 72hrs, I had to reach out to Squarespace tech support, and they confirmed that the domain namePassing the image/file uploaded in form to openai api
I'm trying to use the OpenAI's new vision feature where we can send image through Api. What I want is the user to upload an image in the form and send this image to OpenAI. But I can't access this image properly in deluge script. There are also some constraintsMy client requires me to have custom pdf file names to except payment for invoices, how can I customize this before emailing.
Hello! I love the program so far but there are a few things that are standing in the way. I hope you guys can code them in so I can keep the program for years to come. My client requires I customize the pdf file names I send in for billing. Can you pleaseDisable All
I want to disable all the fields on the form when it loads. I know there is a way to do this by listing all the fields as follows: disable Name; disable Address; disable City; ... I have over 50 fields on my form and i am wondering if there is a single command or way to just disable all fields on load. On load = disable All Thank you for any help.Migrating my email from GMAIL to ZOHO MAIL..........
I am a long time GMAIL user and I really only understand how they operate, but after reviewing your tutorials and forums online, it is quite unbelievable how much more and how much more streamlined ZOHO mail is, not to mention ZOHO's wonderful, more advanced capabilities. I do have several questions about transitioning over to ZOHO. Primarily, where is the best place to start, what do I do first? And how hard is it actually to move all my business and personal accounts over here? When I sign upiOS Zoho Mail App Crashesruni
Whenever I trying to search emails via the Zoho Mail app on my iPhone the app crashes, I am running the latest version of the app and the latest iOS version. I have all set reset the app and deleted the app and still have the same issue. Thank you inAssessment Answered - Automation (Related List)
Hello everyone, We have linked a candidate assessment to our job posting. When someone applies, they are required to answer all the assessment questions. However, some candidates submit their applications without completing the questions. In such cases,Paid Support Plans with Automated Billing
We (like many others, I'm sure) are designing or have paid support plans. Our design involves a given number of support hours in each plan. Here are my questions: 1) Are there any plans to add time-based plans in the Zoho Desk Support Plans feature? TheCan't change form's original name in URL
Hi all, I have been duplicating + editing forms for jobs regarding the same department to maintain formatting + styling. The issue I've not run into is because I've duplicated it from an existing form, the URL doesn't seem to want to update with the newCalendar report with order options and more quick view templates
I think many of us regularly work with calendar-style reports. It would be great to be able to customize the quick view with new templates and have options to sort the entries for each day of the calendar by different criteria. I think this is an interestingShared Views
Hello, is there a way to prevent an agent from changing a shared table view? I have no issues with agents being able to create and customize their own view, but when I create a view and share it to my team -- the expectation is that they are viewing itUsing Zoho answer bot across departments (help center articles from another department)
Hi Zoho Community, I’ve run into a major issue and hope someone here has experience with this setup. We currently have a Help Center in the department A where all of our knowledge base articles are maintained. However, we would like to use a Zoho AnswerNext Page