Kaizen #82 - Search Records API(V4)

Kaizen #82 - Search Records API(V4)

Hello everyone!
Welcome back to this week's Kaizen post!
Today, we will discuss Search API(in version 4), the various supported operators, and how you can use these operators to search for data in different fields of a module.

First off, let us discuss:

When you should use the Search API

You can also use this API when you want to search for a specific text, phone or email in the records of a module, or when you want to do a text-based module-level word search. Search API is the go-to API when you know the details like email, phone or a specific text, but not the individual IDs of the records.

For example, when you want to render a search box in your web/mobile UI, and do a module-level search for the word, use Search Records API.

Search vs Query API

You should use the search records API when you want to perform a text-based search across the module, search for phone or emails fields exclusively, and when you do not know the record IDs.
You can also opt for this API when the maximum number of records you want to fetch per API call is less than 200.

Use the query API when you want to use advanced comparators to query for records from a custom view(without actually creating one), do a cross-module search(through lookup fields), or use aggregate functions.
Opt for this API when you want to fetch up to 2000 records in an API call.

Encoding

When there are parentheses or a comma in your search value, you must escape them and then encode the characters. For example, to search for Patricia(Boyle), you must escape the parentheses as Patricia\(Boyle\) followed by encoding the value as Patricia%5C%28Boyle%5C%28.
When there are special characters in the search value such as +, : etc, you must encode them. Example: Modified_Time%3Agreater_equal%3A2023-04-20T05%3A58%3A06%2B05%3A30 for
Modified_Time:greater_equal:2023-04-19T05:58:06+05:30

Request Details
Request URL: {{api-domain}}/crm/v4/{{module_api_name}}/search
Scope: ZohoCRM.modules.{module_name}.ALL/READ (and) ZohoSearch.securesearch.READ
Parameters specific to Search API: email, phone, word, criteria
Other parameters: fields, converted, approved, page, per_page

1. word

Use this parameter to do a global search of a word in all records and fields of the module.
Note that the search term must have at least three characters to perform a search.

Example
{{api-domain}}/crm/v4/Contacts/search?word=ABC&per_page=3&fields=Last_Name,Account_Name,Full_Name

The response contains the records that have "ABC" in any of their fields.

Response
{
    "data": [
        {
            "Full_Name": "test2k abc",
            "Last_Name": "abc",
            "Account_Name": null,
            "id": "3652397000011831001"
        },
        {
            "Full_Name": "Daly",
            "Last_Name": "Paul",
            "Account_Name": {
                "name": "ABC",
                "id": "3652397000007505116"
            },
            "id": "3652397000007505119"
        },
        {
            "Full_Name": "test2000",
            "Last_Name": "test2000",
            "Account_Name": {
                "name": "ABC",
                "id": "3652397000003098017"
            },
            "id": "3652397000009873004"
        }
    ],
    "info": {
        "call": false,
        "per_page": 3,
        "next_page_token": "74d1d2c0xxx5fe1b",
        "count": 3,
        "sort_by": "id",
        "page": 1,
        "previous_page_token": null,
        "page_token_expiry": "2023-04-22T16:48:05+05:30",
        "sort_order": "desc",
        "email": false,
        "more_records": true
    }
}

2. email

This parameter searches the email fields(including custom email fields) of the module and returns the matching records.
If you have special characters in the email ID, you must encode them to get the exact records.
If you do not encode, then the response will have all the records with the matching email ignoring the special character. 
For example, if the email ID is p+boyle@abc.com, and you do not encode, the response will contain email IDs such as p.boyle@abc.com, p.boylex@abc.com, p.daly@zylker.com etc. 

Example
{{api-domain}}/crm/v4/Contacts/search?email=p%2Bboyle%40abc.com&fields=Email,Last_Name

Response
{
    "data": [
        {
            "Email": "p+boyle@abc.com",
            "Last_Name": "abc",
            "id": "3652397000011831001"
        }
    ],
    "info": {
        "call": false,
        "per_page": 200,
        "next_page_token": null,
        "count": 1,
        "sort_by": "id",
        "page": 1,
        "previous_page_token": null,
        "page_token_expiry": null,
        "sort_order": "desc",
        "email": false,
        "more_records": false
    }
}

3. phone

This parameter searches the phone fields(including custom phone fields) of the module and returns the matching records.

Example
{{api-domain}}/crm/v4/Contacts/search?phone=%2B075-244562374&fields=Last_Name,Phone

Response
{
    "data": [
        {
            "Last_Name": "Smith",
            "Phone": "075-244562374",
            "id": "3652397000010134055"
        },
        {
            "Last_Name": "Gayle",
            "Phone": "+075-244562374",
            "id": "3652397000011831001"
        }
    ],
    "info": {
        "call": false,
        "per_page": 200,
        "next_page_token": null,
        "count": 2,
        "sort_by": "id",
        "page": 1,
        "previous_page_token": null,
        "page_token_expiry": null,
        "sort_order": "desc",
        "email": false,
        "more_records": false
    }
}

4. criteria

Use this parameter when you want to search for records based on a certain criteria. 
The format is (({api_name}:{operator}:{value})and/or({api_name}:{operator}:{value}))

The following table gives you the field types and the operators you can use in the "criteria" parameter.

Field Type
Operator
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
Lookup(user/owner)
equals, not_equal, in
Picklist, Autonumber
equals, not_equal, in
Text, Email, Phone, Website
equals, not_equal, starts_with, in


Let us discuss each of these field types with examples.

4.1 Date in criteria

Supported operators: equals, not_equal, greater_equal, greater_than, less_equal, less_than, between, in

{{api-domain}}/crm/v4/Deals/search?criteria=(Closing_Date:between:2022-12-10,2022-12-21)&fields=Last_Name,Amount,Closing_Date

4.2 DateTime in criteria(search value encoded)

Supported operators: equals, not_equal, greater_equal, greater_than, less_equal, less_than, between, in
Here, the value in the Modified_Time field is Modified_Time:greater_equal:2023-04-19T05:58:06+05:30 and contains the special characters :, +, -. So, you must escape these characters and then encode them. 
The encoded value is Modified_Time%3Agreater_equal%3A2023-04-19T05%3A58%3A06%2B05%3A30

{{api-domain}}/crm/v4/Deals/search?criteria=Modified_Time%3Agreater_equal%3A2023-04-19T05%3A58%3A06%2B05%3A30&fields=Last_Name,Amount,Closing_Date

4.3 Currency and Decimal in criteria

Supported operators: equals, not_equal, greater_equal, greater_than, less_equal, less_than, between, in

{{api-domain}}/crm/v4/Deals/search?criteria=((Probability:between:70,90) AND (Amount:less_equal:75000))&fields=Amount,Probability

4.4 Boolean in criteria

Supported operators: equals, not_equal

{{api-domain}}/crm/v4/Leads/search?criteria=(Email_Opt_Out:equals:true)&fields=Last_Name,Company&per_page=2

4.5 Lookup in criteria

Supported operators: equals, not_equal, in
Here, Account_Name is the lookup field in the Contacts module and points to the Accounts module.

{{api-domain}}/crm/v4/Contacts/search?criteria=(Account_Name:in:Zylker,ABC)&fields=Last_Name,Company,Account_Name&per_page=5

4.6 Picklist in criteria

Supported operators: equals, not_equal, in
Here, Languages_Known is a custom picklist field in the Contacts module. This request fetches all the records that contain "English" or "French" or both in the Languages_Known picklist.

{{api-domain}}/crm/v4/Contacts/search?criteria=(Languages_Known:in:English,French)&fields=Last_Name,Company,Languages_Known&per_page=5

 4.7 User/Owner Lookup in criteria

Supported operators: equals, not_equal, in
To search based on Owner fields, you must use the ID of the users as the search value.

{{api-domain}}/crm/v4/Contacts/search?criteria=(Owner:in:3652397000000186017,3652397000000281001)&fields=Last_Name,Company,Owner&per_page=5

4.8 Text in criteria

Supported operators: equals, not_equal, starts_with, in

{{api-domain}}/crm/v4/Contacts/search?criteria=(Department:starts_with:s)&fields=Last_Name,Department

4.9 Email in criteria

Supported operators: equals, not_equal, starts_with, in

{{api-domain}}/crm/v4/Contacts/search?criteria=(Email%3Aequals%3Ap%2Bboyle%40abc.com)&fields=Last_Name,Email

Here, the email "p+boyle@abc.com" has a special character(+) and so, must be encoded to get the right response.

4.10 Phone in criteria

Supported operators: equals, not_equal, starts_with, in

{{api-domain}}/crm/v4/Contacts/search?criteria=(Phone%3Ain%3A%2B075-1111111%2C888-555-2145)&fields=Last_Name,Phone

Here, the phone numbers +075-1111111 and 888-555-2145 are the search values for the Phone field. As they both contain special characters, we have encoded them. 

4.11 Website in criteria

Supported operators: equals, not_equal, starts_with, in

{{api-domain}}/crm/v4/Leads/search?criteria=(Website:starts_with:https)&fields=Last_Name,Website

Note

  • You can search for a maximum of 10 criteria (with same or different columns) with equals and starts_with conditions.
  • When you use "equals" for multiple conditions, and if one of your conditions is (Company:equals:ABC), the response will contain records with ABC as well as ABC Inc in their Company fields.
  • When you use "equals" with a single condition and search for a field, like (Campaign_Name:equals:CRM), the response will contain only those records whose Campaign_Name is "CRM" and not records with "Best CRM" or "Latest CRM" in their Campaign_Name fields.
  • The phone, word, and email parameters search for all fields whose datatype is phone, text, and email, respectively. But, when you use them in the criteria parameter, the search is restricted only to that particular field as you give the field's API name.

We hope you found this post useful. We will see you next week with another interesting post.
Let us know your questions and feedback in the comment section, or write to us at support@zohocrm.com.


Cheers!

    • 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

    • How to upload own video?

      How can you upload your own video on your zoho website? I do not want to use another host, but i want to insert my own files. how can i do this?

    • Searching customer field

      Hello, When entering a receipt, we select customer information. The customer information is synced with Zoho CRM. However, we can't find the customer information because it searches for words that begin with the entered value. It needs to search for words

    • 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,

    • Rotate an Image in Workdrive Image Editor

      I don't know if I'm just missing something, but my team needs a way to rotate images in Workdrive and save them at that new orientation. For example one of our ground crew members will take photos of job sites vertically (9:16) on his phone and upload

    • Improved RingCentral Integration

      We’d like to request an enhancement to the current RingCentral integration with Zoho. RingCentral now automatically generates call transcripts and AI-based call summaries (AI Notes) for each call, which are extremely helpful for support and sales teams.

    • Resume Harvester: New Enhancements for Faster Sourcing

      We’re excited to share a set of enhancements to Resume Harvester that make sourcing faster and more flexible. These updates help you cut down on repetitive steps, manage auto searches more efficiently, and review candidate profiles with ease. Why we built

    • Using Zoho Flow to create sales orders from won deal in Zoho CRM

      Hi there, We are using Zoho Flow to create sales orders automatically when a deal is won in Zoho CRM. However, the sales order requires "Product Details" to be passed in "jsonobject", and is resulting in this error: Zoho CRM says "Invalid input for invalid

    • WIDGET in related record list ZOHO CRM; how to get and put data to subform custom fields?

      he need: Read and write two custom subform line-item fields on Quotes: Segment_wyceny (picklist/text) and W_pakiecie (number). Write works; read does not return these fields via SDK. Environment Zoho CRM Widget Zoho Embedded App SDK v1.2 Module: Quotes

    • Cliq iOS can't see shared screen

      Hello, I had this morning a video call with a colleague. She is using Cliq Desktop MacOS and wanted to share her screen with me. I'm on iPad. I noticed, while she shared her screen, I could only see her video, but not the shared screen... Does Cliq iOS is able to display shared screen, or is it somewhere else to be found ? Regards

    • Zoho CRM Tracking Google Enhanced Conversions

      Can anyone @Zoho, consultants, or users help me understand if Zoho CRM is going to support Google's Enhanced Conversions? I included some information from Google below about it. We use Google Adwords for our pay per click advertising for lead generation,

    • zoho click, and nord VPN

      Unfortunately, we've been having problems with Zoho Click, where essentially the line cuts off after about a minute's worth of conversation every time we are on VPN. Is there a way we can change this within the settings so it does not cut the line off

    • Recurring Supervisor Rule Reminders for Open/In-Progress Tickets

      Hello Zoho Support Team, I would like to suggest a potential improvement regarding reminders for tickets and activities in Zoho Desk. Currently, it is possible to set reminders only once. In the Supervisor Rules section, it is possible to configure reminders

    • Connecting Portals from different Zoho apps

      Hi, I note that Zoho has functionality for customer portals for several of the Zoho apps, like CRM, Projects, Desk etc. Is there any way to connect these portals?  It would be great if we could give our customers access to a portal in which they could

    • Billing Management: #5 Usage Billing

      After understanding the nuances of Advance Billing and Retainers, we will explore one of the booming billing models. Long ago, villagers drew water from a shared well in a small village. The well was a lifeline for the entire community. Ravi, the well

    • Function #10: Update item prices automatically based on the last transaction created

      In businesses, item prices are not always fixed and can fluctuate due to various factors. If you find yourself manually adjusting the item rates every time they change, we have the ideal time-saving solution for you. In today's post, we bring you custom

    • Inventory Adjustments

      Hi, How to transfer the material from one head to another ? Like materials purchased for manufacturing the laptop need to transfer from consumption inventory (Quantity of raw materials reduced) to destination inventory ( Quantity of Laptop increased)

    • Zoho CRM Community Digest - Aug 2025 | Part 1

      Hey everyone! The first half of August went by, and we have a few announcements and some good noteworthy discussions. So, let's take a look at them! Product Updates: Introducing Connected Records feature: Zoho CRM’s Next-Gen UI now includes Connected

    • Problems with email templates (HTML - Outlook)

      Hi there, I've been trying to create a newsletter from the template "Business 4". Everything looks great in the preview, but when I send it to my Outlook inbox, the layout doesn't seems to stick. More particularly: - The line-height is way more reduced, even though I used the line-height tool from the template - Columns but they are sometimes misaligned - Font size is not always the one I've selected. Could you help? Thanks!

    • Please make it easier to Pause syncing

      right now it takes 3 clicks to get there. sounds silly, but can you make it just 2 clicks to get it done instead? thats how dropbox does it, 2 clicks to pause instead of 3.

    • 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

    • Create static subforms in Zoho CRM: streamline data entry with pre-defined values

      Last modified on (9 July, 2025): This feature was available in early access and is currently being rolled out to customers in phases. Currently available for users in the the AU, CA, and SA DCs. It will be enabled for the remaining DCs in the next couple

    • SalesIQとPageSenseの利用について

      初めての投稿で場違いだったらすいません。 弊社ではSalesIQを運用しているのですが、追加でPageSenseの導入もしたいと現場からの声があります。 両サービスともクッキー同意バナーが必要なサービスなのですが 弊社では同意無しに情報はとりませんという方針なので 2つ入れると2つバナーを出す必要がでてきます・・・ 両サービスを運用されてる方があれば運用状況とか教えてほしいです。 PageSenseについては詳細まで機能を理解してないなかでの質問です。

    • How to integrate Zoho Forms with Zoho CRM on Standard Plan

      Hello Zoho Support Team, I am using the Standard Zoho Forms plan (USD 30/user) and I would like to integrate Zoho Forms with Zoho CRM so that certain fields in my forms can be automatically prefilled using data from Deals in CRM. Specifically, I want

    • CRM : Function to add user name to text field

      I have a lookup field in a module that is linked to the CRM users so we can assign a Project Lead to the customer. Sadly Zoho Marketing Automation doesn't sync Lookup fields so I need to extract information from the lookup to text fields: Lookup field

    • Export PDF File Name

      Is it possible to change the default Zoho .pdf naming scheme for inventory items like quotations? Would like to use the the Subject as the default quote name. Is this possible?

    • How to change the from address from 'no reply' for an email template in CRM

      Hi, We have our CRM set up with the from field as sales@XXX. I have just created a series of email templates and sent a test and they are sending from noreply@zoho I have tried searching for how to change the email template but don't have the options

    • Zoho CRM Client Script - SetCriteria in lookup Field

      Hello All One More Zoho CRM Client Script Tips & Trick. Now you can Set the Criteria on Your lookup in zoho CRM, It Comes With a Create Page, Edit Page, and Details Page (Standard). Example:- We have a Room Module that includes Room Name, Status, Campus,

    • Kaizen #71 - Client Script ZDKs for Detail (Canvas) Page

      Hello everyone! Welcome back to another interesting Kaizen post. In this post, we can discuss Client Script ZDKs support for Detail (Canvas) Page. What is Detail (Canvas) Page? A Detail(Canvas) Page allows you to customize the record detail page to your

    • how to use validation rules in subform

      Is it possible to use validation rules for subforms? I tried the following code: entityMap = crmAPIRequest.toMap().get("record"); sum = 0; direct_billing = entityMap.get("direct_billing_details"); response = Map(); for each i in direct_billing { if(i.get("type")

    • Add Custom Reports To Dashboard or Home Tab

      Hi there, I think it would be great to be able to add our custom reports to the Home Tab or Dashboards. Thanks! Chad

    • Rich-text fields in Zoho CRM

      Hello everyone, We're thrilled to announce an important enhancement that will significantly enhance the readability and formatting capabilities of your information: rich text options for multi-line fields. With this update, you can now enjoy a more versatile

    • Create Lead Button in Zoho CRM Dashboard

      Right now to create Leads in the CRM our team is going into the Lead module, selecting the "Create Lead" button, then building out the lead. Is there anyway to add the "Create Lead" button or some sort of short cut to the Zoho CRM Dashboard to cut out

    • 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

    • Validation Rule Not Working for Mandatory Field in Zoho Blueprint

      As a Zoho user, we created a validation rule for a specific field. However, we noticed that when we made the same field mandatory within a Blueprint, the validation rule we defined did not work. When we reported this issue to Zoho Support, they stated

    • Notes Issues

      Been having issues with Notes in the CRM. Yesterday it wasn't showing the notes, but it got resolved after a few minutes., Now I have been having a hard time saving notes the whole day. Notes can't be saved by the save button. it's grayed out or not grayed

    • Export from Contacts module to Products module in Zoho CRM

      Good afternoon, I would like to send a number of contact info from the Contacts module into the customized module (tickets to an event) in one operation. I have selected several contacts in the Contact module (people who I have labelled as people I want

    • Zoho Commerce

      Hi, I have zoho one and use Zoho Books. I am very interested in Zoho Commerce , especially with how all is integrated but have a question. I do not want my store to show prices for customers that are not log in. Is there a way to hide the prices if not

    • Can’t receive emailI c

      I have generated a basic for but when I submit it I don’t get a email, I’ve been in the settings and tested me email, all appears correct, can you please help me

    • Data Capture for Historical Activity (Especially One Lead Downloading Variois reports without Overwriting the info)

      Is there a better way in Zoho CRM to capture and archive a lead’s historical activity—specifically whenever they download reports—so that the data is stored without being overwritten?”

    • Client Script - Updating Field Value in Detail Page of a Lead

      Hello, I'm trying to use Client Script To enrich some data of the Lead when one of my User fill the "City" field in the detail page of the Lead. This is my Script: log (value); var response = ZDK.Apps.CRM.Functions.execute("getInfoCitta", { "nomeCitta":

    • Next Page