Kaizen #29 - Parameters in Zoho CRM APIs [Part 1/2]

Kaizen #29 - Parameters in Zoho CRM APIs [Part 1/2]

Hello everyone!

Welcome back to another week of Kaizen!
In this post, we will shed some light on the Parameters in Zoho CRM APIs.

What will you learn from this post?

In this post we will discuss the parameters in Get Records API. In our upcoming post, we will discuss parameters in Search Records API and other generic parameters available in Zoho CRM APIs.

Parameters in Get Records API

Parameters in Zoho CRM APIs allow you to filter records based on your needs. For instance, if you want to retrieve the records in a specific custom view, you can filter the results by adding a cvid parameter, with the unique ID of the custom view. Now, let us discuss about each parameter in detail. All the parameters that are listed below are optional.

a. fields
Use this parameter to retrieve the specific fields in the response, instead of the entire JSON file. For instance, if you want to retrieve just the Last Name and the Email ID of the Leads, you can use the fields parameter.
In the fields parameter, specify comma-separated API names of the fields that you want to retrieve.

Apart from the Get Records API, you can use this parameter in the Get Notes API.

b. sort_order & sort_by
Use these parameters to sort the records that you retrieve in either ascending or descending order. The system behaves differently, based on whether you have specified the sort_by field.
sort_order accepts the following string values:
  • asc: To sort the records in ascending order.
  • desc: To sort the records in descending order. This is the default value. 
sort_by accepts valid module-specific filed API names.

Case 1: When you specify both sort_order and sort_by
If you specify both sort_by and sort_order field, the system sorts the records based on the value in the sort_by field in the order specified in sort_order parameter. In the screenshot below the records are sorted based on Email in descending order. 


Case 2: If you specify only the sort_order
If you specify only the sort_order, the system sorts the records based on the unique ID of the record. In the screenshot below, the Leads are sorted based on "id" in ascending order. 



Case 3: If you specify only the sort_by
If you specify only the sort_by, the system sorts the records based on the value in the sort_by field in descending order.
In the screenshot below, the Leads are sorted based on the value in the "No_of_Employees" field in descending order. 

Apart from the Get Records API, you can use this parameter in the Get Notes API

c. converted
Use this parameter to get the list of records based on whether they are converted or not. For instance, the Leads that were converted into Contact or Account (or) Quotes that were converted into Sales Orders or Invoices can be retrieved using this parameter.
The parameter accepts only boolean value:
  • true: Retrieves converted records.
  • false: Retrieves records that are not converted.
Supported Modules
Leads, Quotes


Apart from the Get Records API, you can use this parameter in the Search Records API.

d. approved
Use this parameter to retrieve the records involved in the approval process
The parameter accepts only the boolean value:
  • true: Retrieves records that are approved.
  • false: Retrieves records that are still in the approval process.

Apart from the Get Records API, you can use this parameter in the Search Records API

e. page & per_page
Use this parameter to retrieve records based on their position in the CRM. The default value for the page parameter is 1, and the per_page parameter is 200. You can retrieve a maximum of 200 records per API call.

For instance, let us assume that you need to fetch 400 records. Then, you need to make two API calls:
(i) With parameters page=1 and per_page=200
The request fetches the first 200 records in the Leads module.


(ii) With parameters page=2 and per_page=200
The request fetches records that are positioned from 201 to 400 in the Leads module. 


The "more_records" key represents if there are more records present in subsequent positions in that particular module.
  • true: There are more subsequent records in the module.
  • false: There are no more records in the module.
Other APIs in which you can use page & per_page parameters:

f. cvid
Use this parameter to retrieve records in a custom view. Specify the unique ID of the custom view as value. 


g. territory_id & include_child
Use this parameter to retrieve records in a specific territory. Specify the unique ID of the territory in the territory ID parameter, and specify whether you want to include child territories in include_child parameter. 
include_child accepts only boolean value:
  • true: Retrieves records in the child territory.
  • false: Retrieves records only in the parent territory. This is the default value.
Note that Territory is supported only for the modules Deals, Contacts, and Accounts. 


Refer to Kaizen #25 Zoho CRM API - Common Errors and Error Handling to know about the errors related to parameters.

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

Cheers!






                            Zoho Desk Resources

                            • Desk Community Learning Series


                            • Digest


                            • Functions


                            • Meetups


                            • Kbase


                            • Resources


                            • Glossary


                            • Desk Marketplace


                            • MVP Corner


                            • Word of the Day



                                Zoho Marketing Automation



                                        Manage your brands on social media



                                                Zoho TeamInbox Resources

                                                  Zoho DataPrep Resources



                                                    Zoho CRM Plus Resources

                                                      Zoho Books Resources


                                                        Zoho Subscriptions Resources

                                                          Zoho Projects Resources


                                                            Zoho Sprints Resources


                                                              Qntrl Resources


                                                                Zoho Creator Resources


                                                                  Zoho WorkDrive Resources



                                                                    Zoho Campaigns Resources

                                                                      Zoho CRM Resources

                                                                      • CRM Community Learning Series

                                                                        CRM Community Learning Series


                                                                      • Tips

                                                                        Tips

                                                                      • Functions

                                                                        Functions

                                                                      • Meetups

                                                                        Meetups

                                                                      • Kbase

                                                                        Kbase

                                                                      • Resources

                                                                        Resources

                                                                      • Digest

                                                                        Digest

                                                                      • CRM Marketplace

                                                                        CRM Marketplace

                                                                      • MVP Corner

                                                                        MVP Corner


                                                                            Design. Discuss. Deliver.

                                                                            Create visually engaging stories with Zoho Show.

                                                                            Get Started Now