Get Records, Search Records, Query and Bulk Read APIs

Get Records, Search Records, Query and Bulk Read APIs

Hi everyone.. Welcome back!

In this post, we will discuss when to use Get Records, Search Records, Query, and Bulk Read APIs to fetch records. Please note that the information in the article holds true for version 3 of Zoho CRM APIs.

Get Records API

The GET Records API allows you to fetch all the records from a module in your CRM account. 

When should you use GET Records API?

       Use this API to fetch a specific set of records whose IDs you already know, or to fetch all the records from a module without any filters, or using the pre-defined filters.
      For instance, when you want to render a mobile/web UI to show the list of records in a module or a specific custom view, you can make use of Get Records API.

Pagination

  • You can retrieve up to 200 records using this API in a single call.
  • To fetch more than 200 records, you must use pagination and make further API requests with the page parameter.
  • For more than 2000 and up to a maximum of 100,000 records, use the page_token parameter in the request. The value for this parameter is available from the key "next_page_token" in the response of the first Get Records call. 
  • You cannot use the page_token parameter with the page parameter.

Points to remember

  • You should specify the field API names to fetch the records.
  • You can fetch up to 50 fields using this API.
  • You can sort the records by id, Created_Time and Modified_Time fields.
  • Each Get Records API call consumes one API credit.

Examples

1. To fetch the records from 1801-2000 in the Leads module with the Last_Name and Email fields

The info JSON object in the response contains the next_page_token to retrieve the next set of records. 

2. To fetch after 2000 records
 [GET] "https://www.zohoapis.com/crm/v3/Leads&fields=Last_Name,Email&per_page=200 
&page_token="db8d4276axxxxxxx713748a4e""

Search Records API

Search Records API lets you search for records in a module based on a criteria that you define. You can search for records with a specific word in the text fields, or by email or phone fields across the specified module. You can also search for a variety of other fields like currency, Date, DateTime, picklists etc.

When should you use Search Records API?

      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 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. 

Pagination

  • You can search for up to 200 records in one API request.
  • To fetch more than 200 and up to 2000 records, use the page parameter.

Points to remember

  • Your search criteria can have  equals, starts_with, in, equals, not_equal, greater_equal, greater_than, less_equal, less_than, starts_with, or between conditions.
  • There will be a delay in accessing recently inserted or updated records using this API due to data indexing.
  • Due to the indexing delay, it is advised not to use Search API to check for record duplication while creating a new record. 
  • Each Search Records API call consumes one API credit. 

Examples

1. To search for all the Leads with the word Zoho in the record

2. To fetch records from the Leads module whose Last_Name is 'Thomas' and First_Name starts with 'M'

Query API

Query API lets you query for records based on queries using the CRM Object Query Language(COQL). COQL is based on the SQL query syntax, and supports the SELECT query to fetch records. Using this API, you can query for data across different modules that are linked using lookup fields.  This API allows you to search for a variety of fields like picklist, Date, DateTime, Lookup, Number, Currency, Boolean, or string fields, and sort the records on the basis of any field.

When should you use Query API?

      To query for a module's data and its lookup related data using various comparators, or when you want to query for records that fall into a custom view without actually creating one.
      For instance, when you want to filter all the products in a specific price range, with 4 stars and up rating, use Query API.
      You can also use Query API to query for records from cross module (linked via lookup field). Eg: Filtering deals based on the account's location and industry type. In this example, Deals is the primary module linked with Accounts module via the lookup field 'Accounts_Name'.

Pagination

  • You can retrieve 200 records in one API call using this API.
  • To fetch more than 200 records and upto 10000 records, use the OFFSET clause. 

Points to remember

  • You can use DB comparators such as =, >, <, >=, <=, is null, is not null, between, in, not in, like, and not like in your search query.
  • You can fetch a maximum of 10000 records using this API.
  • You can use Query API to check for record duplication while creating a new record in your web/mobile UI apps.
  • Each Query API call consumes one API credit.

Examples

1. Cross Module Filtering : To filter deals based on its corresponding account's location and industry type.

"select_query": "select Deal_Name, Stage, Probability, Type, Account_Name from Deals where ((Account_Name.Location = 'Texas') AND (Account_Name.Industry = 'Military'))"

2. Consider the following custom view.

You can fetch the records in the custom view using the following SELECT query, without actually creating the custom view.
 { "select_query": "select Last_Name, Owner.last_name from Leads where ((Industry  = 'ERP') and (Owner = '4876876000000327001')) OR (Rating =    'Acquired')" }

For more examples, refer to our Get Records through COQL page. 
TIP : If you want to fetch all the records in a module using COQL Query API, you can still use the COQL query to do it. For example, the below example will fetch all the records in the Leads module.
   {  "select_query": "select Last_Name, Owner.last_name from Leads where ((Industry  = 'ERP') OR (Industry  != 'ERP'))"}

Bulk Read API

Bulk Read API lets you export data in bulk from a module. Using this API, you can export records based on a query, or export all the records in a module with or without filters. The main advantage of Bulk read API is in the huge number of records it can retrieve in one API call. While you can fetch 200 records per API call for GET Records API, Search Records API and Query API, you can export 200,000 records per API call using the Bulk read API. 

When should you use Bulk read API?

When you want to schedule a job to export huge volume of CRM data.
For instance, when you want to export the list of all the records from a  Zoho CRM  module to sync with your local ERP system's data store, use Bulk read API. 

Points to remember

  • Bulk read is an asynchronous API.
  • The result of the bulk read job will be available as a downloadable CSV/ICS file.
  • Each Bulk read API call consumes 50 API credits.
  • To export more than 200,000 records, use the page key in the request body. Setting page to '2' exports data starting from 200,001.

Sample Scenario

Let us now consider the case where you want to fetch (a)2000, (b)5000, (c)10000 and (d)15000 records from a module, and see which API is best-suited for each case.

 Number of records
 Get Records API
Search Records API
Query API
Bulk read API
2000
  • 10 API calls
  • 10 API credits
  • Use pagination
  • 10 API calls
  • 10 API credits
  • Use pagination
  • 10 API calls
  • 10 API credits
  • Use OFFSET
  • 1 API call
  • 50 API credits
5000
  • 25 API calls
  • 25 API credits
  • use pagination (up to 2000 records) & page_token (after 2000 records)

Not possible to fetch more than 2000 records
  • 25 API calls
  • 25 API credits
  • Use OFFSET 
  • 1 API call
  • 50 API credits
10000
  • 50 API calls
  • 50 API credits
  • use pagination (up to 2000 records) & page_token (after 2000 records)

Not possible to fetch more than 2000 records
  • 50 API calls
  • 50 API credits
  • Use OFFSET
  • 1 API call
  • 50 API credits

15000
  • 75 API calls
  • 75 API credits
  • use pagination (up to 2000 records) & page_token (after 2000 records)

Not possible to fetch more than 2000 records

Not possible to fetch more than 10000 records
  • 1 API call
  • 50 API credits

To sum up, for up to 2000 records, the Get Records API, Search Records API, and Query API all use the same API credits. However, Query API has the edge over the other two because it provides you with greater flexibility to tweak your criteria, thanks to all the comparators and logical operations it supports.  If you intend to fetch 10,000 or more records asynchronously, the Bulk Read API is preferable in terms of API credits consumed. For synchronously fetching more than 10,000 records, use the Get Records API.


Feature
Get Records API
Search Records API
Query API
Bulk Read API
Maximum number of records per API call
 200
 200
 200
 200,000
 For Events - 20,000
Maximum number of records that can be fetched
 100,000
 2000
 10,000
 100,000,000
Indexing Delay
 No 
 Yes
 No 
 NA
Pagination
Use page parameter to retrieve more than 200 records and page_token parameter for more than 200 recordsUse page parameter to retrieve up to 2000 recordsUse LIMIT and OFFSET to navigate and retrieve a maximum of up to 10,000 recordsUse page key in the request body to fetch more than 200,000 records. Maximum possible value for page is 500
Sorting supportLimited (id, Created_Time and Modified_Time fields )
 No
 Yes
 No
Credits per API call
 1
 3 - with CVID parameter
 1
 1
 50

We hope you found this post useful. Let us know your thoughts in the comment section or reach out to us at support@zohocrm.com

Thank You!