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

    • Feature Request: Conditional Field Mandatoriness Based on Display Status

      Hello Zoho Creator Team, I would like to suggest an enhancement to improve the flexibility of form validations. Currently, when we need a field to be mandatory only if it's displayed on the form, the only option is to: Set the field as not mandatory in

    • Im Stuck in an EDIT ONLY WITH WIZARD issue

      So I found Wizards to be a really helpful tool in minimizing the exposure of redundant, superfluous fields to staff that would never otherwise have to edit those fields. My issue is, that when the record (in this case a lead) is created with a wizard,

    • Data Migration Strategies for Moving to a Cloud Solution

      Hi everyone, I’ve been working on moving some of our critical systems, including CRM and project data, to a Zoho cloud solution, and one of the biggest challenges I’ve encountered is data migration. Transferring large volumes of data while keeping it

    • Bulk Moving Images into Folders in the Library

      I can't seem to select multiple images to move into a folder in order to clean up my image library and organize it. Instead, I have to move each individual image into the folder and sometimes it takes MULTIPLE tries to get it to go in there. Am I missing

    • Error 550 5.4.1

      I’ve tried sending an email to someone but keep receiving this back. Any help would be greatly appreciated 

    • Automatic Matching from Bank Statements / Feeds

      Is it possible to have transactions from a feed or bank statement automatically match when certain criteria are met? My use case, which is pretty broadly applicable, is e-commerce transactions for merchant services accounts (clearing accounts). In these

    • Has Anyone successfully integrated Zoho and Sage Intact?

      Hey all, We’re evaluating Zoho One + Sage Intacct and I’m trying to connect with anyone who has actually implemented the two together.Specifically, I’d love to know: -- Which functions you kept in Zoho vs. Intacct (e.g., Product Catalog, AR/AP, invoicing,

    • Store "Sign in with Google/Microsoft/GitHub etc." details

      Quite often now, users are using a sign-in provider like Google or Microsoft to sign into various apps and services. It would be great if Vault could remember which providers you use for each website and sign you in with that provider instead of a username

    • Placing a condition before converting the LEAD

      Hi,  I need some assistance with Lead conversion. I need to place certain conditions before allowing the user to convert the lead.  For example: up until the certain status's doesn't equal "green" don't allow to convert lead.  I tried creating this using

    • Subform edits don't appear in parent record timeline?

      Is it possible to have subform edits (like add row/delete row) appear in the Timeline for parent records? A user can edit a record, only edit the subform, and it doesn't appear in the timeline. Is there a workaround or way that we can show when a user

    • Unable to retrieve Contact_Name field contents using Web API in javascript function

      Hello, I've added a field in the Purchase Order form to select and associate a Sales Order (Orden_de_venta, lookup field). I've also created a client script to complete some fields from the Sales Order (and the Quote), when the user specifies the related

    • How can I filter a field integration?

      Hi,  I have a field integration from CRM "Products" in a form, and I have three product Categories in CRM. I only need to see Products of a category. Thanks for you answers.

    • Adding image in HTML report page

      Hi, I want to know two things: 1. Can anyone advise how to add an image in HTML report. The tagged used is <img> but what path do I mention for the image to be added in the HTML report. 2. Also, I want to know if I am creating an application for the market

    • How to change view of HTML report based on device but always print in A4

      Hello everyone, I am aware that HTML report view can be configured to adjust according to the screen size like Laptop, Tablet and mobile using media queries. But my concern is no matter on which device the reports is opened when printed should always

    • Age Calculation

      I've attempted to calculate the age of someone based on their birthday input by using the formula field. It works but I don't want all those decimals on there. I then tried to use "set variable" after birthday input but I get a field type mismatch, long vs. floating. Any ideas would be wonderful.

    • Search on Custom Field

      We're working on an integration with the Zoho FSM API and are trying to retrieve companies based on a custom field we added to the Companies module. However, we can't find a way to filter or query records using custom fields through the API. We have a

    • in zoho creator Sales Returns form has sub form Line Items return quantity when i upate the or enter any values in the sub form that want to reflect in the Sales Order form item deail sub form field Q

      in zoho creator Sales Returns form has sub form Line Items return quantity when i upate the or enter any values in the sub form that want to reflect in the Sales Order form item deail sub form field Quantity Returned\ pls check the recording fetch_salesorder

    • Sendmail function / custom action?

      I've setup a function hoping to email various business departments the details of a record once all work in that record is complete so gone about setting up a custom action in such way that each record line on the report has a button to click. Question is how do I actually include data from that record in the email that is sent when the button is clicked? I had thought that since this were being sent per record the email would include the data which had been entered

    • API to post drafts for social media

      I we want to post draft posts to our zoho social account and then approve and schedule them within Zoho social. is this possible with for example: https://apis.zoho.com/social/v2/post TIA Jon

    • Integración Books para cumplir la ley Crea y Crece y Ley Antifraude (VeriFactu)

      Hola: En principio, en julio de 2025, entra en vigor la ley Crea y Crece y Ley Antifraude (VeriFactu). ¿Sabéis si Zoho va a cumplir con la ley para cumplir con la facturación electrónica conectada a Hacienda? Gracias

    • Is there an API to "File a Ticket" in Desk

      Hi, Is there an API to "File a Ticket" in Desk to zoho projects?

    • Unarchive tickets

      How can I manually unarchive tickets?

    • Canvas View in Zoho Recruit

      Is it possible or would it be possible to have the new 'Canvas View' in Zoho Recruit?

    • What impactful sales coaching techniques have you used to boost your team's performance?

      I'm curious about the real-world impact of sales coaching on team performance. What specific techniques or strategies have you found most effective in driving consistent improvement and growth in your sales team? Any success stories or lessons learned

    • Adding Taxes to paid consultations in Zoho Bookings

      I created a 'paid' consultation under Zoho Booking and integrated it with payment gateways for online/instant payment before a booking is done. How can I add 'taxes' to the price of consultation? I can add taxes to other Zoho apps (liks Books, Checkout,

    • Zoho Finance Suite - Customer Custom Tabs - Dynamic Link

      Hi Finance Suite team, When creating a Custom Tab for a Client Portal, there is no option to add dynamic parameters. This would be very helpful for adding Zoho Analytics dashboards which can be dynamically filtered through the URL to only show information

    • Optimize your Knowledge Base for enhanced accessibility by adding alt tags for images

      Let's learn why alt tags are crucial for your articles. You can add alternative tags (alt tags) and alternative text (alt text) to the images you share on your community forums or when embedding them in articles. Alt tags refer to the HTML attribute,

    • Feature Request - Insert URL Links in Folders

      I would love to see the ability to create simple URL links with titles in WorkDrive. or perhaps a WorkDrive extension to allow it. Example use case: A team is working on a project and there is project folder in WordDrive. The team uses LucidChart to create

    • Formula field with IF statement based on picklist field and string output to copy/paste in multi-line field via function

      Hello there, I am working on a formula field based on a 3-item picklist field (i.e. *empty value*, 'Progress payment', 'Letter of credit'). Depending on the picked item, the formula field shall give a specific multi-line string (say 'XXX' in case of 'Progress

    • FSM trying again

      have not linked FSM yet to the rest of out Zoho suit. It certainly looks like the apointment and service part is more manageable for our staff. The question is that our engineers multi task examples 1. deliver products to customers not fitted 2. Service

    • Possible to bold or indent text in the description field?

      As part of one item, I often have a detailed description that would be much easier to read if there was the ability to have a bulleted list or bold text and the like. Is this possible? My last invoicing software allowed markup in the field so, for example, an asterisk meant a bullet. I haven't been able to find any documentation related to this.  Any information would be appreciated. Thank you.

    • How can I setup Zoho MCP with Chat GPT

      I can set up custom connections with Chat GPT but I cat an error when I try to set it up. The error is: "This MCP server can't be used by ChatGPT to search information because it doesn't implement our specification: search action not found" Thoughts?

    • Formatting of Balance Sheet and Profit & Loss Reports

      The default format of the Balance Sheet and P&L Reports are based on the Account Types and then the individual accounts within the Chart of Accounts. These are then ordered alphabetically under these sub-headings and one is unable to re-order these or

    • UK MTD reports concerning turnover and cerash accounting

      Hi I am a sole trader, and I have just started with Zoho Books in order to comply with the new HMRC requirements. I use 'cash basis' - which I understand to mean that income is when the cash comes in (not the invoice date) and expenses are when they are

    • Retainer Invoice.

      Why ZOHO not have facilities to deduct partially advance payment from an invoice.

    • Collaborate Feature doesn't work

      Hello Team. It seems that the collaborate section is broken? I can post something but it all appears in "Discussions". In there is no way how I would mark something as Draft, Approval, post or any of the other filter categories? Also if I draft a post

    • IMAP Server not responding.

      Trying to connect a phone via IMAP and getting "imap.zoho.com not responding." Is the server down, for maintenance or otherwise? I've tried this on two different devices and got the same error on both.

    • Vendor Signatures Needed for Purchase Orders

      Hello everyone, We have a unique requirement that necessitates that Vendors & Suppliers formally acknowledge our Purchase Orders upon receipt. I was hoping that there would be an option to do so in Zoho Books, but that does not appear to be the case.

    • Share saved filters between others

      Hi, I am in charge to setup all zoho system in our company. I am preparing saved filters for everybody, but the only one can see its me. How can others see it? Thanks

    • report showing assignment type

      Hi, We've created a number of workflows to allow us to auto assign tickets to agents based on keywords and other criteria. I'm struggling to create a report that would show me what is the percentage of tickets that are assigned automatically via workflows

    • Next Page