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!

Access your files securely from anywhere

Zoho Developer Community

New to Zoho LandingPage?

Access Zoho LandingPage

Zoho LandingPage Resources

New to Zoho Survey?

Access Zoho Survey

Latest Feature Updates

Explore our Pricing & Plans

Zoho Survey Resources

Android Mobile Surveys

Insurvey Blogs

Insight Blogs

Tips & Tricks

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Bigin?

Signup Now

Access Bigin

Latest Feature Updates

Zoho Desk Resources

Desk Community Learning Series
Digest
Functions
Meetups
Kbase
Resources
Glossary
Desk Marketplace
MVP Corner
Word of the Day

Tout forum

France ZUGs

Zoho SalesIQ Resources

Sticky Posts
Kaizen#162 : Add Tags and Open Pre-filled Email Drafts via Client Scripts
Hello everyone! Welcome to another informative Kaizen post. In this post, let us see how to accomplish the following using Client Script. 1. How to auto-tag a record based on field update? 2. How to Open a pre-filled email draft This post will provide
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
Extension Pointers - JS SDK series #4: Managing data from a widget using ZOHO.CRM.HTTP
Handling and managing the data between two applications is a major factor for an efficient business. There are a variety of ways to handle data between Zoho CRM and other third-party applications. You can use deluge CRM tasks, create connectors, use API
Kaizen #152 - Client Script Support for the new Canvas Record Forms
Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved
Extension pointers for integrating Zoho CRM with Zoho products #8: Upload and manage Zoho Workdrive folders and files from within Zoho CRM
Keeping records on your customers and business prospects is essential for tracking data, conducting follow-ups, and running a business smoothly. When you use two separate applications, and store relevant data in each, checking and tracking data becomes