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 #197: Frequently Asked Questions on GraphQL APIs

      🎊 Nearing 200th Kaizen Post – We want to hear from you! 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 #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.

    • Celebrating 200 posts of Kaizen! Share your ideas for the milestone post

      Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQs

    • Kaizen #193: Creating different fields in Zoho CRM through API

      🎊 Nearing 200th Kaizen Post – We want to hear from you! 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.

    • Client Script | Update - Introducing Commands in Client Script!

      Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands

    • Recent Topics

    • Weekly Tips : Customize your Compose for a smoother workflow

      You are someone who sends a lot of emails, but half the sections in the composer just get in your way — like fields you never use or sections that clutter the space. You find yourself always hunting for the same few formatting tools, and the layout just

    • Zoho Slowness - Workarounds

      Hi all, We've been having intermittent slowness and Zoho just asks for same stuff each time but never fix it. It usually just goes away on it's own after a couple weeks. Given that speed is a very important thing for companies to be able to keep up with

    • Custom Bulk Select Button

      Zoho CRM offers the ability to select multiple records and invoke a Custom Button This functionality is missing from Recruit Currently we can only add buttons in the detail page and list But we cannot select Multiple Records and invoke a function with

    • How to create a Zoho CRM report with 2 child modules

      Hi all, Is it possible to create a Zoho CRM report or chart with 2 child modules? After I add the first child module, the + button only adds another parent module. It won't let me add multiple child modules at once. We don't have Zoho Analytics and would

    • Zoho CRM still doesn't let you manage timezones (yearly reminder)

      This is something I have asked repeatedly. I'll ask once again. Suppose that you work in France. Next month you have a trip to Guatemala. You call a contact there, close a meeting, record that meeting in CRM. On the phone, your contact said: "meet me

    • Power of Automation :: Smart Ticket Management Between Zoho Desk and Projects

      Hello Everyone, A custom function is a software code that can be used to automate a process and this allows you to automate a notification, call a webhook, or perform logic immediately after a workflow rule is triggered. This feature helps to automate

    • First day of trying FSM in the field.

      What we found. 1. with out a network connection we were unable to start a service call? 2. if you go to an appointment and then want to add an asset it does not seem possible. 3. disappointed not to be able to actually take a payment from within the app

    • BUG - Google Business Buttons - Add a button to GBP Post

      I am experiencing an issue with the "Add a button" feature when creating posts for my Google Business Profile (GBP) through Zoho Social. When I schedule or publish a GBP post and include a call-to-action button with a specific URL, the post itself publishes

    • Rich text Merge field - Not using font specified in HTML

      I have a rich text merge field in a writer template which is creating a table. I have chosen to use this method instead of a repeat region because I need to specify specific cell background colours which change every time the document is created. The

    • Support for Custom Fonts in Zoho Recruit Career Site and Candidate Portal

      Dear Zoho Recruit Team, I hope you're doing well. We would like to request the ability to use custom fonts in the Zoho Recruit Career Site and Candidate Portal. Currently only the default fonts (Roboto, Lato, and Montserrat) are available. While these

    • CC and/or BCC users in email templates

      I would like the ability to automatically assign a CC and BCC "User (company employee)" into email templates. Specifically, I would like to be able to add the "User who owns the client" as a CC automatically on any interview scheduled or candidate submitted

    • Trying to export a report to Excel via a deluge script

      I have this code from other posts but it gives me an error of improper statement, due to missing ; at end of line or incomplete expression. Tried lots of variations to no avail. openUrl(https://creatorapp.zoho.com/<username>/<app name>/XLSX/#Report:<reportname>,"same

    • Zoho Reports Duplicating Entries

      I have a custom costing tab with a table where we entre invoices. These are under a Heading (PO Subject) and notes added in the form with different line items. In the reports, I have organised the report to group per PO Subject, with the total of the

    • Need help to create a attach file api

      https://www.zoho.com/crm/developer/docs/api/v8/upload-attachment.html Please help me to create it... It's not working for while. Do you have some example?

    • Export view via deluge.

      Hi, Is it possible to export a view (as a spreadsheet) via deluge? I would like to be able to export a view as a spreadsheet when a user clicks a button. Thanks     

    • how to add subform over sigma in the CRM

      my new module don't have any subform available any way to add this from sigma or from the crm

    • Outdated state in mexico

      Hello Zoho team, the drop down to add the state for customers, when they introduce their state in mexico has a city named “Distrito Federal” that name changed many years ago to “ciudad de mexico”. could you please update this so my clients can find the

    • Support new line in CRM Multiline text field display in Zoho Deluge

      Hi brainstrust, We have a Zoho CRM field which is a Muti Line (Small) field. It has data in it that has a carriage return after each line: When I pull that data in via Deluge, it displays as: I'm hoping a way I can change it from: Freehand : ENABLED Chenille

    • Possible to generate/download Quote PDF using REST API?

      See title. Is there any way after a quote has been created to export to a PDF using a specified template and then download it? Seems like something that should be doable. Is this not supported in the API v2.0?

    • Creating an invoice to be paid in two installments?

      Hi there, I own a small Photographic Services business and have not been able to find a way to fit my billing system into Zoho, or any other Accounting software. The way my payments work is: 1. Customer pays 50% of total price of service to secure their

    • Bug in allowing the user to buy out of stock items

      Hi i want to allow the user to buy out of stock items, according to the commerce documentation if i disable Restrict "Out of stock" purchases it will, but it doesnt work, so i want to know if it had any relation with zoho inventory, and if theres any

    • Zoho CRM Calendar | Custom Buttons

      I'm working with my sales team to make our scheduling process easier for our team. We primary rely on Zoho CRM calendar to organize our events for our sales team. I was wondering if there is a way to add custom button in the Calendar view on events/meeting

    • Replace Lookup fields ID value with their actual name and adding inormation from subforms

      Hi everyone,  I wanted to see if someone smarter than me has managed to find any solutions to two problems we have. I will explain both below.  To start we are syncing data from Zoho CRM to Zoho Analytics and I will use the Sales Order module when giving

    • Can a Zoho Sites page be embedded into another website (outside Zoho)

      Hi All, We have a request from a client - they'd like to take one of our information pages created in Zoho Sites and embed it into their own website? I was told through an email with Zoho that this was possible >>Thank you for your patience regarding

    • Bug in allowing the user to buy out of stock items

      Hi i want to allow the user to buy out of stock items, according to the commerce documentation if i disable Restrict "Out of stock" purchases it will, but it doesnt work, so i want to know if it had any relation with zoho inventory, and if theres any

    • Transition Criteria Appearing on Blueprint Transitions

      On Monday, Sept. 8th, the Transition criteria started appearing on our Blueprints when users hover over a Transition button. See image. We contacted Zoho support because it's confusing our users (there's really no reason for them to see it), but we haven't

    • Zoho CRM Sales Targets for Individual Salespeople

      Our organistion has salespeople that are allocated to different regions and have different annual sales targets as a result. I am building an CRM analytics dashboard for the sales team, which will display a target meter for the logged in salesperson.

    • All new Address Field in Zoho CRM: maintain structured and accurate address inputs

      The address field will be available exclusively for IN DC users. We'll keep you updated on the DC-specific rollout soon. It's currently available for all new sign-ups and for existing Zoho CRM orgs which are in the Professional edition. Managing addresses

    • Transfer all Related Data to new Account Owner

      Currently when I change the account Owner I only see the option to change only the open deals But I want the new account owner to take over all the related modules and all the deal stages Is it not possible right now? Am I missing something? Do I really

    • Can i connect 2 instagram accounts to 1 brand?

      Can i connect 2 instagram accounts to 1 brand? Or Do i need to create 2 brands for that? also under what subscription package will this apply?

    • How to Calculate MTTR (Mean Time to Resolve)

      We want to calculate MTTR (Mean Time to Resolve) in our Zoho Analytics report under Tickets. Currently, we are using the following fields: Ticket ID Ticket Created Time Ticket Closed Time Ticket On Hold Time We are planning to calculate MTTR (in days)

    • How to export project tasks, including the comments

      Hi, how can I export the project tasks, whereby I can also see the comments associated to a specific task? The use-case is that often we use comments to discuss or update a task related ideas. I would like to export the tasks, where we can also see the

    • How to Install Zoho Workdrive Desktop Sync for Ubuntu?

      Hi. I am newbie to Linux / Ubuntu. I downloaded a tar.gz file from Workdrive for installing the Workdrive Desktop Sync tool. Can someone give me step by step guide on how to install this on Ubuntu? I am using Ubuntu 19.04. Regards Senthil

    • Introducing Version-3 APIs - Explore New APIs & Enhancements

      Happy to announce the release of Version 3 (V3) APIs with an easy to use interface, new APIs, and more examples to help you understand and access the APIs better. V3 APIs can be accessed through our new link, where you can explore our complete documentation,

    • Round robin

      Hi, I'm trying to set up a round robin to automatically distribute tickets between agents in my team but only those tickets that are not otherwise distributed by other workflows or direct assignments. Is that possible and if so which criteria should I

    • Does Zoho Sheet Supports https://n8n.io ?

      Does Zoho Sheet Supports https://n8n.io ? If not, can we take this as an idea and deploy in future please? Thanks

    • Bigin Android app update: User management

      Hello everyone! In the most recent Bigin Android app update, we have brought in support for the 'Users and Controls' section. You can now manage the users in your organization within the mobile app. There are three tabs in the 'Users and Controls' section:

    • Share records with your customers and let them track their statuses in real time.

      Greetings, I hope everyone is doing well! We're excited to introduce the external sharing feature for pipeline records. This new enhancement enables you to share pipeline records with your customers via a shareable link and thereby track the status of

    • Live webinar: Discover Zoho Show: A complete walkthrough

      Hello everyone, We’re excited to invite you to our upcoming live webinar, Discover Zoho Show: A Complete Walkthrough. Whether you’re just getting started with Show or eager to explore advanced capabilities, this session will show you useful tips and features

    • Deal Stage component/widget/whatever it is... event

      Deal Stages I am trying to access the event and value of this component. I can do it by changing the Stage field but users can also change a Deal Stage via this component and I need to be able to capture both values. Clicking on 'Verbal' for instance,

    • Next Page