Kaizen #178 - Filters & Criteria in Zoho CRM APIs

Kaizen #178 - Filters & Criteria in Zoho CRM APIs


Hey everyone, and welcome back to another week of Kaizen!

Ever felt overwhelmed by the sheer volume of data in your Zoho CRM? Sifting through countless records to find exactly what you need, or to operate on specific records that meet a certain criteria, can indeed be a real time-sink. Fortunately, Zoho CRM provides powerful filtering capabilities through its APIs to streamline this process.

What is criteria or filter?

In Zoho CRM APIs, criteria refer to the conditions applied to filter records when making API requests. These conditions can be simple (single condition) or complex (multiple conditions) and are specified using various comparators.

Depending on the API type and request method, the filter can be provided either:
  • As a query parameter (filters) – Used in GET requests.
  • As an input key in the request body (criteria)– Used in POST and PUT requests   

Where is "filters" used in Zoho CRM APIs?

The filters parameter is supported across multiple Zoho CRM API endpoints, including but not limited to:

Where is "criteria" used in Zoho CRM APIs?

The criteria key is supported across multiple Zoho CRM API endpoints, including but not limited to:
The filters parameter and criteria key are supported across multiple Zoho CRM API endpoints. Refer to our API help documentation for individual APIs to check if these options are available. Check the Parameters section for filters and the Input JSON section for criteria
 in the API's help documentation.

Constructing a criteria or a filter

Zoho CRM APIs use JSON-based criteria/filters expressions, which consist of:
  • Field API Name – The field to filter (e.g., Email, Created_Time, Status).
  • Comparator – The operator defining how the field should be compared (equals, greater_than, etc.).
  • Value – The specific value to compare against.

Single Condition

A single condition is structured as follows:
{
  "field": {
    "api_name": "Post_Number"
  },
  "comparator": "greater_than",
  "value": 1
}

Here,
  • field specifies the API name of the field to be filtered.
  • comparator indicates the type of comparison to be made (e.g., greater_than).
  • value is the value against which the field is compared.

Multiple Conditions

When multiple conditions are required, they can be grouped using the logical operators "and" or "or". Here’s the syntax of how to structure multiple conditions:
{
  "group_operator": "or",
  "group": [
    {
      "field": {
        "api_name": "Post_Number"
      },
      "comparator": "greater_than",
      "value": 1
    },
    {
      "field": {
        "api_name": "Pre_Number"
      },
      "comparator": "greater_than",
      "value": 1
    }
  ]
}

Here,
  • group_operator can be "and" or "or". It defines how the conditions within the group array are evaluated. "and" means all conditions must be true, while "or" means at least one condition must be true.
  • group
     contains an array of condition objects, each with its own field, comparator, and value.
Following is an example for a criteria with more than two conditions:
{
  "criterion": {
    "group_operator": "and",
    "group": [
      {
        "field": {
          "api_name": "Post_Number"
        },
        "comparator": "greater_than",
        "value": 1
      },
      {
        "group_operator": "or",
        "group": [
          {
            "field": {
              "api_name": "Pre_Number"
            },
            "comparator": "greater_than",
            "value": 1
          },
          {
            "field": {
              "api_name": "Status"
            },
            "comparator": "equals",
            "value": "Active"
          }
        ]
      }
    ]
  }
}

Supported Comparators for Different Field Types

The available comparators depend on the field type. The following table outlines the supported comparators for different field types:

Field Type
Supported Comparators
Example
text/ textarea
equal, not_equal, contains, not_contains , starts_with, ends_with
{
   "comparator": "equal",
   "field": {
       "api_name": "text"
   },
   "value": "zoho"

}
email
equal, not_equal, contains, not_contains, starts_with, ends_with
{
   "comparator": "contains",
   "field": {
       "api_name": "Email"
   },
   "value": "patricia"
}
phone
equal, not_equal, contains, not_contains, starts_with, ends_with
{
   "comparator": "equal",
   "field": {
       "api_name": "Phone"
   },
   "value": "9999999999"
}
website
equal, not_equal, contains, not_contains, starts_with, ends_with
{
   "comparator": "contains",
   "field": {
       "api_name": "website"
   },
   "value": "zoho"
}
picklist
equal, not_equal, contains, not_contains, starts_with, ends_with
{
   "comparator": "equal",
   "field": {
       "api_name": "picklist"
   },
   "value": [
       "Cold Call",
        "Call"
   ]
}
multiselectpicklist
equal, not_equal, contains, not_contains, starts_with, ends_with
{
   "comparator": "equal",
   "field": {
       "api_name": "Multi_Select_Picklist"
   },
   "value": [
         "Cold Call",
        "Call"
   ]
}
date
equal, not_equal, less_than, greater_than, between, not_between, less_equal, greater_equal
Example 1:
{
   "comparator": "less_than",
   "field": {
       "api_name": "date"
   },
   "value": "01-01-2025"

}
Example 2:
{
   "comparator": "between",
   "field": {
       "api_name": "date"
   },
   "value": [
          "01-01-2025",
           "02-01-2025",
}
datetime
equal, not_equal, less_than, greater_than, between, not_between, less_equal, greater_equal
{
   "comparator": "equal",
   "field": {
       "api_name": "date"
   },
   "value": "2025-01-01T12:12:06+05:30"
}
autonumber
equal, not_equal, contains, not_contains, starts_with, ends_with
{
   "comparator": "starts_with",
   "field": {
       "api_name": "Auto_Number"
   },
   "value": "A01"
}
integer
equal, not_equal, less_than, less_equal, greater_than, greater_equal, between, not_between
{
   "comparator": "equal",
   "field": {
       "api_name": "integer"
   },
   "value": 4
}
currency
equal, not_equal, contains, not_contains, starts_with, ends_with
{
   "comparator": "equal",
   "field": {
       "api_name": "Currency"
   },
   "value": "INR"
}
double
equal, not_equal, less_than, less_equal, greater_than, greater_equal, between, not_between
{
   "comparator": "equal",
   "field": {
       "api_name": "Double"
   },
   "value": "123"
}
Boolean
equal
{
   "comparator": "equal",
   "field": {
       "api_name": "Boolean"
   },
   "value": true
}
big int
equal, not_equal, less_than, less_equal, greater_than, greater_equal, between, not_between
{
   "comparator": "equal",
   "field": {
       "api_name": "id"
   },
   "value": "1234800023843923"
}
lookup
equal, not_equal, less_than, less_equal, greater_than, greater_equal, between, not_between
{
   "comparator": "equal",
   "field": {
       "api_name": "Lookup.name"
   },
   "value": "Name1"
}
ownerlookup/userlookup
in, not_in 
{
   "comparator": "equal",
   "field": {
       "api_name": "Modified_By",
       "id": "400029000000000479"
   },
   "value": [
       {
           "id": "400029000003984001",
           "name": "User1"
       },
       {
           "id": 400029000003984002,
           "name": "User2"
       }
   ]
}
formula
Comparator will depend on the return type
-



Notes
Note: 
  • Use quotes for strings and picklists; do not use quotes for numbers and boolean values.
  • While Zoho CRM’s filtering capabilities are extensive, certain field types — including subforms, multi-select lookup fields, multi-user lookup fields, and multi-module lookup fields — are not supported in filters and criteria. The above table lists all the supported field types. 

Filtering in COQL Queries

COQL (CRM Object Query Language) provides a structured way to retrieve records from Zoho CRM using SQL-like queries. Unlike the standard API filters discussed above, COQL uses the WHERE clause to define conditions.

Here is a sample COQL query:

{
  "select_query": "SELECT Full_Name, Email FROM Leads WHERE Lead_Status = 'Qualified'"
}

Here, Lead_Status = 'Qualified' acts as the filtering criteria.

{
  "select_query": "SELECT Full_Name, Email FROM Leads WHERE (Lead_Status = 'Qualified' AND City = 'New York') OR (Industry = 'Software')"
}

The AND and OR operators allow for multiple conditions in the WHERE clause. We have covered COQL API, and all the supported field types and operators in detail in our Kaizen posts. Kindly refer to them for more details.

Criteria in Search API

In Search API, filtering records is done using the criteria (string) input key in the request body. Unlike filters in GET requests or criteria in other APIs, criteria here is a text-based filter expression that follows a specific syntax.

(({api_name}:{operator}:{value})and/or({api_name}:{operator}:{value}))
  • You can combine up to 10 conditions using and or or.
  • Only the equals operator is supported for encrypted fields.
  • When using "equals" in Search API, it behaves like "contains", meaning it fetches records that include the specified value, not just exact matches.
  • If you use parentheses (), commas, or backslashes \ in values, you must escape them properly and encode the value before making the request.
Field Type
Supported Operators
Date, DateTime
equals, not_equal, greater_equal, greater_than, less_equal, less_than, between, in
Integer, Currency, Decimal
equals, not_equal, greater_equal, greater_than, less_equal, less_than, between, in
Boolean
equals, not_equal
textarea
equals, not_equal, starts_with
Lookup (user/owner)
equals, not_equal, in
Picklist, Autonumber
equals, not_equal, in
Text, Email, Phone, Website 
equals, not_equal, starts_with, in
multiselectpicklist
equals, not_equal, in, starts_with.
bigint
equals, not_equal, greater_than, greater_equal, less_than, less_equal, between, in
percent
equals, not_equal, greater_than, greater_equal, less_than, less_equal, between, in
formula
The supported operators of the formula datatype will depend on the return type of the formula


Have questions or use cases to share? Feel free to share them in the comments below or reach out to our support team directly at support@zohocrm.com.

Thank you for joining us this week. Stay tuned for more insights in our upcoming Kaizen posts! Happy Coding!!



    • 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

    • Why is Zoho Meeting quality so poor?

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

    • Integration between "Zoho Sprints Stories" and "Zoho Projects Tasks/Subtasks"

      We have two separate teams in our organization using Zoho for project management: The Development team uses Zoho Sprints and follows Agile/Scrum methodology. The Infrastructure team uses Zoho Projects for traditional task-based project management. In

    • Where can we specify custom CSS in Zoho Forms custom theme ?

      I'm using a form with a dark theme. The OTP popup window is unreadable, because for some reason, the OTP popup background fixes color to white, but still takes the font color specified in the custom theme. This ends up as white on white for me, rendering

    • Team Gamification

      Would love to motivate, engage and encourage our team with our social media posts. Would like to include Gamification features of Social Media in Zoho Social or Marketing Automation. And also bring in Social Advocacy tools/tracking/management to these,

    • Sync Data from MA to CRM

      Currently, it's a one-way sync of data from the CRM to MA. I believe we should have the ability to select fields to sync from MA to the CRM. The lead score is a perfect example of this. In an ideal world we would be able to impact the lead score of a

    • Update CRM record action

      Currently, MA only offers a "Push Data" action to push data to a CRM module. This action is built to cover the need to both create a new record and update an existing record. Because it has been implemented this way all required fields on the CRM module

    • Pro Lite Upgrade - Quick Access Tray

      Hello, I was going to upgrade to Pro Lite but the Quick Access Tray feature isn't available for Windows. Of the four features not available for Windows, the QAT is what I'm most interested in. Are there plans to add this feature for Windows anytime soon?

    • Boost your CRM communication with new font types, sizes, and default reply-to options while composing emails

      Hello Everyone, We’re excited to introduce a series of impactful enhancements to the email composer settings in Zoho CRM. These updates enable you to personalize and optimize your customer interactions with greater efficiency. So what's new? Add custom

    • Feature Enhancement Request – Text Formatting Options in Item Description (Zoho Books/Quotes Module)

      Dear Zoho Development Team, Greetings from Radiant360 Integrated Technical Services LLC. We would like to bring to your attention a functional limitation we've encountered within the Item Table / Quote Description section of Zoho Books (and Zoho CRM Quotes).

    • 3 year sick leave cycle

      How do you set up a sick leave cycle for South Africa? In SA the sick works like this for the first 6 months you get 0.83 paid sick days a month, then after 6 months you sick leave balance is reset to 30 days that can be used over a 36 month cycle.  This

    • WorkDrive and CRM not in sync

      1/ There is a CRM file upload field with WorkDrive file set as the source: 2/ Then the file is renamed in WorkDrive (outside CRM): 3/ The File in CRM is not synced after the change in WorkDrive; the file name (reference) in CRM record is not updated (here

    • Is Zoho Communityspaces now part of Zoho One?

      Is Zoho Communityspaces now part of Zoho One?

    • Bigin’s 2025 Evolution: Highlights from 2025 and What’s Ahead in 2026

      Dear Biginners, Wishing you a very happy New Year! As we stand at the cusp of endless possibilities in 2026, we would like to take a moment to reflect on what we achieved together in 2025. Your continued support, thoughtful feedback, and kind words of

    • Send Supervisor Rule Emails Within Ticket Context in Zoho Desk

      Dear Zoho Desk Team, I hope this message finds you well. Currently, emails sent via Supervisor Rules in Zoho Desk are sent outside of the ticket context. As a result, if a client replies to such emails, their response creates a new ticket instead of appending

    • Zoho Desk - Change Time Zone for all users and set default for new user

      Hi,   Is there a way to set a default time zone so that when user creates an account via the Zoho Desk invitation, they don't need to select the time zone via the hundreds of choice?   And, for already created users, can we edit the incorrect time zone selected by the user at the account creation ?   Thanks ! Fred

    • Allow Manual Popup Canvas Size Control

      Hello Zoho PageSense Team, We hope you're doing well. We would like to request an enhancement to the PageSense popup editor regarding popup sizing. Current Limitation: Currently, the size (width and height) of a popup is strictly controlled by the selected

    • Why does Zoho’s diff viewer highlight parts of unchanged lines?

      Hi everyone, I’ve noticed something odd in the Zoho editor’s diff view. When I delete a single line, the diff doesn’t just mark that line as removed. Instead, it highlights parts of the next line as if they changed, even though they are identical. Example:

    • Add deluge function to shorten URLs

      Zoho Social contains a nice feature to shorten URLs using zurl.co. It would be really helpful to have similar functionality in a Deluge call please, either as an inbuilt function or a standard integration. My Creator app sends an email with a personalised

    • form data load issue when saving as duplicate record is made

      Hello. I have a form with a lookup when a value is selected the data from the corresponding record is filled into all of the fields in the form. But the form is loaded in such a state that if any value is changed it will take all of the values pre loaded

    • Invoice template, how to change the text under "Notes" and "Terms and Conditions"

      In "Invoice templates", there are two text/info sections at the bottom:"Notes" and "Terms and Conditions". It is possible to change the names of these two headings, but how is it possible to change/alter the text under it. As a standard it says "Thank you for your business" under Notes - I need to change it into something different- How? Thank you.

    • Recurring Tasks and Reminders in Projects

      Recurring tasks are tasks that are created once, and then recreated automatically after a designated time period. For example, the invoice for your billable tasks is due every week. You can set that task to recreate itself every week. Also, the future

    • Unable to remove the “Automatically Assigned” territory from existing records

      Hello Zoho Community Team, We are currently using Territory Management in Zoho CRM and have encountered an issue with automatically assigned territories on Account records. Once any account is created the territory is assigned automatically, the Automatically

    • Improved Functionality PO Bill SO Invoice

      Hello, I need to enter over 100 items, it's frustrating to scroll a few item rows and wait for more to load, then scroll again. It would be nice to have buttons that scroll to the top or bottom with one click. Furthermore, these items I'm adding are VAT

    • Wishes for 2026

      Hello, and a happy new year 2026! Let's hope it's better for everyone. I'd like to share some thoughts on Zoho One and what could be useful in the short, medium, and long term. Some things are already there, but not applied to Zoho One. Others seem like

    • How to Integrate Zoho Books with Xero (No Native Connection Available)

      Hi everyone, I’m currently facing an issue with integrating Zoho Books invoices with Xero, as I’ve noticed Zoho does not provide a native integration with Xero at this time. I would like to ask: What are the common or recommended solutions for syncing

    • Markup instead of discount??

      Is it possible to have the discount field on an invoice or estimate be a markup instead? It's the very same functionality that I am looking for - to be able to markup an individual item by either a $ or a % and have that cost added (instead of subtracted) to the item cost.  Currently, I use the tax feature to accomplish this, but it's very awkward to have "Markup 15%" listed after the subtotal. Plus, if I want to markup items at different rates, I end up with several "markup" lines in the totals

    • Plan switch

      I thought I pressed the Free button, but after they set up the account, I see that I am on a Premium trial. Is this usual? How do I get onto the Free version?

    • 'Tax registration date'?

      The second question in setting up is 'Tax registration date'. My first question: which tax? My second question: why do you need the registration date?

    • What if we don't have an ABN?

      Australian business. Setting up. We have no ABN. It's not compulsory. Field not allowed to be blank. What to do?

    • Linking Multi-UOM Barcodes to Products in Zoho Books

      Greetings, I'm using Zoho Books for retail shop and I'm running into a bit of a challenge with products that have multiple Units of Measurement (UOMs) and corresponding barcodes. For example, I sell cigarettes both as individual packets and in cartons

    • How to change "from" email address when invoicing.

      HELP! I'm new to Zoho Books and when I first set it up used a different email address than I currently want to use. I've tried to go to settings and change the default email address but when I generate an invoice it still shows the old email address (although I can't find it anywhere else). I really need to get this changed before I can use the program. Any help would be appreciated.

    • Critical Issue: Tickets Opened for Zoho Support via the Zoho Help Portal Were Not Processed

      Hi everyone, We want to bring to your attention a serious issue we’ve experienced with the Zoho support Help Portal. For more than a week, tickets submitted directly via the Help Portal were not being handled at all. At the same time no alert was posted

    • Hide/Show Subform Fields On User Input

      Hello, Are there any future updates in Hide/Show Subform Fields "On User Input"?

    • Cloning Item With Images Or The Option With Images

      Hello, when I clone an item, I expect the images to carry over to the cloned item, however this is not the case in Inventory. Please make it possible for the images to get cloned or at least can we get a pop up asking if we want to clone the images as

    • Custom validation in CRM schema

      Validation rules in CRM layouts work nicely, good docs by @Kiran Karthik P https://help.zoho.com/portal/en/kb/crm/customize-crm-account/validation-rules/articles/create-validation-rules I'd prefer validating data input 'closer to the schema'

    • Adding Default Module Image into mail merge field

      As with most people finding their way to these forums i have a specific requirement that doesn't seem to be supported by Zoho I have created 2 custom modules to suit my purpose 1 is an inventory type module that lists aluminium extrusions, and all relevant

    • Is it possible to roll up all Contact emails to the Account view?

      Is there a way to track all emails associated with an Account in one single view? Currently, email history is visible when opening an individual Contact record. However, since multiple Contacts are often associated with a single Account, it would be beneficial

    • Managing credit cards

      Hi, I'm hoping someone on this forum can help me out managing credit card accounts.  Transaction are entered as expenses using the credit card account and, as expected, the card balance shows as a negative since this is clearly money I owe them.  Once I make a payment, of the full amount owed, I woudl expect the balance to become zero. It doesn't, the negative balance just keeps on increasing even though the payment is reflected correctly in my main operating account.  No-one at Zoho seems to understand

    • Free Training - Explore What’s New in Zoho One 2025

      Greetings! We hope you have all had a chance by now to get hands-on with the new features and updates released as part of ZO25. Yes, we understand that you may have questions and feedback. To ensure you gain a comprehensive understanding of these updates,

    • Quick way to add a field in Chat Window

      I want to add Company Field in chat window to lessen the irrelevant users in sending chat and set them in mind that we are dealing with companies. I request that it will be as easy as possible like just ticking it then typing the label then connecting

    • Next Page