Accessing Subform using Zoho CRM APIs

Hello everyone!

Welcome back to another post in our Kaizen series.

In this post, we will discuss how to manipulate the Subform data using Zoho CRM APIs.

Subforms

A Subform is a data section embedded in the primary form to collect details related to the parent record. It helps in maintaining multiple records under a single parent record.

Using subform, you can create a parent-child relationship between modules, where the parent module represents the primary data and the child module contains the related data.

Data Model Representation

The above diagram shows the data model representation when you create a subform in a module.
Consider adding a subform field named Project Details in the Leads module (parent module). Zoho CRM will automatically create a separate module for the subform field with the specified subform field name - Project Details. Each record within the subform module can have multiple fields, in addition to the system-defined Parent_Id lookup field, establishing a connection between the parent (Leads module) and child (subform module) modules. Through this linking process, one can easily identify which subform record corresponds to which specific lead record.

Use Case

Consider Zylker Consulting organization using Zoho CRM to maintain their leads and their projects. Zylker uses the Project Details subform in the Leads module to collect project-specific information collected from their Leads.

The Project Details subform includes fields such as Project Title,Type, Budget, and Status, in addition to the Parent_Id lookup field.

Now, the Zylker's sales team needs to retrieve all the details of the projects from the Leads module for further project analysis, expected budgets, and status. Let's see how to manipulate these data in CRM using Zoho CRM APIs.

The APIs used in this post

API	Methods
Subforms API	GET, POST, UPDATE
Records API	POST, UPDATE, DELETE
Search API	GET
COQL API	POST
Bulk Read API	POST, GET

How to retrieve subform records using the Zoho CRM APIs?

To retrieve subform records from the subform module, specify the subform module's API name to access their records or fields.

Step - 1

To know the API names of the subform fields in a module, make a GET - Fields Metadata API call. Among all the Leads' fields, subform field can be identified by the json key data_type with the value subform. Corresponding subform module can be found from the json associated_module. Below is the API call & response for such a subform field.

Request URL :

{api-domain}/crm/v6/settings/fields/{subform_field_id}?module=Leads

Request Method: GET

Sample Response:

Step - 2

Using the api_name of the subform module, make a GET Fields metadata API call to get the list of fields (along with their api_name) in the subform. One of the fields of the subform module will be Parent_Id with the data_type as lookup, pointing to the parent module (here it is Leads).

Request URL

https://www.zohoapis.com/crm/v6/settings/fields?module=Project_Details

Request Method: GET

Sample Response:

Now you know how to get the API name of the subform and its corresponding fields.

Step - 3

Sample Request and Response to retrieve subform records

The below request will retrieve all the subform records in the Leads module. The linking of subform record to the Lead's module will be available in the Parent_Id field, which is highlighted. The id key inside the Parent_Id json object is the id of the Leads records.

How to add data to the subforms?

To add records to the subform, you need the API name of the subform and its corresponding field API names.

Request URL:

https://www.zohoapis.com/crm/v6/Leads

Request Method: POST

Sample Input

{

"data": [

{

"Last_Name": "Patricia",

"Company": "Info Technology",

"Email" : "patricia@mail.com",

"Project_Details": //API name of the subform

[

{

"Project_Name": "Mobile App Development for Productivity",

"Project_Type": "Mobile App Development",

"Expected_Budget": 50000,

"Status": "Negotiation in Process"

}, //API names of the subform fields

{

"Project_Name": "Big Data Infrastructure Implementation",

"Project_Type": "Infrastructure Upgrade",

"Expected_Budget": 30000,

"Status": "Proposal Submitted"

{

"Project_Name": "Big Data Infrastructure Implementation",

"Project_Type": "Infrastructure Upgrade",

"Expected_Budget": 30000,

"Status": "Proposal Submitted"

}

]

}

]

}

The above highlighted syntax is used for adding data to the subform records.

Sample Response:

Kaizen #33 - Subforms API explains in detail how to Fetch, Update, and Delete the subform data with sample requests, inputs, and responses.

Retrieve Subform Data via Search API and COQL API

There may be situations where you need to fetch records based upon certain conditions.

Criteria :

The sales team wants to retrieve the subform records whose budget is greater than or equal to $40000. In this case, we will use Zoho CRM's Search API and COQL API. Let's see how to achieve this.

Search API

To retrieve the records that match your search criteria, retrieve subform data using its corresponding module API name. Note that using Search API, you can fetch data quickly from a single module.

Request URL:

https://www.zohoapis.com/crm/v6/Project_Details/search?criteria=Expected_Budget:greater equal:40000

Request Method: GET

Sample Response :

The above response shows all records that meet the specified criteria.

How to retrieve subform records from a particular parent record?

To retrieve subforms records in a particular lead record that meet the above criteria, follow the below sample request.

Sample Request URL:

https://www.zohoapis.com/crm/v6/Project_Details/search?criteria=((Expected_Budget:greater_equal:40000)and(Parent_Id:equals:5725767000002105059))

Sample Response:

Retrieving Subforms Data via COQL API

We know that the subform is maintained in a separate module. So, retrieve subform data by querying the subform module's API name and it's parent module via the Parent_Id lookup field.

Request URL:

https://www.zohoapis.com/crm/v6/coql

Request Method : POST

Sample Input:

{
"select_query" : "select Expected_Budget from Project_Details where ((Expected_Budget >=40000) and (Parent_Id = 5725767000002105043))"
}

Sample Response:

Using a Parent_Id (lookup field pointing to Leads module) in the COQL criteria automatically adds a left join to the child module (Project_Details). With that join, criteria can be applied to the fields of the parent module also. Below example illustrates that we want to fetch the Expected_Budget field of the Project_Details module where the Expected_Budget is greater than or equal to 40000 for the corresponding Leads with Annual Revenue greater than 1000000.

{

"select_query" : "select Expected_Budget from Project_Details where ((Expected_Budget >=40000) and (Parent_Id.Annual_Revenue > 100000 ))"

}

From the SQL perspective, above COQL can be interpreted as

select pd.Expected_Budget from Project_Details as pd left join Leads as l on pd.Parent_Id=l.id where pd.Expected_Budget>=40000 and l.Annual_Revenue > 1000000

For more information on COQL API, refer to the Kaizen posts COQL Part -1 and COQL Part - 2

Bulk Read API

Bulk Read API allows you to fetch a large set of data i.e., you can fetch a maximum of 200,000 records in a single API call.

To export subform records in the Leads module in CSV file format, use the subform's API name.

Request URL:

https://www.zohoapis.com/crm/bulk/v6/read

Request Method: POST

Sample input to export subform records:

{

"callback": {

"url": "https://webhook.site/7b58ff0b-b61b-4fbf-953f-1bf8b180a3c4",

"method": "post"

"query": {

"module": {

"api_name": "Project_Details" //API name of the Subform module

"file_type": "csv"

}

Export subform records that meet the specified criteria

To export subform records based on the given criteria above (similar to the criteria for Search and COQL APIs).

Sample Input:

Export subform records that meet the specified criteria for the particular parent record

To export the subform records of a particular parent record in the Leads module. Check the below sample request.

Sample Input:

{
. . .
"query": {
"module": {
"api_name": "Project_Details"
},
"fields": [
"Project_Name",
"Project_Type",
"Expected_Budget",
"Status"
],
"criteria": {
"group": [
{
"field": {
"api_name": "Expected_Budget"
},
"comparator": "greater_than",
"value": "39999"
},
{
"field": {
"api_name": "Parent_Id"
},
"comparator": "equal",
"value": "5725767000002105043"
}
],
"group_operator": "AND"
}
}
}

As the API is an asynchronous API, the response will not be available instantly; the bulk read job is scheduled, and the status can be checked. Once the job is completed, it'll be notified in the callback URL. The records are available in a downloadable CSV file or ICS file (for events). You can export subform records in a module using the subform module API name. See Kaizen #12 Bulk Read API to know how to view the status of the scheduled job and download the file, along with more sample requests and responses.

Frequently Asked Questions

Q. Is the API name of the subform case-sensitive? Also, how can I view the API name of a subform field in the web UI?

Yes, the API name of a subform is case-sensitive. To know the API name of a subform module (e.g. Project Details) Please go to Setup -> Developer Hub -> APIs -> CRM API -> API names -> Click on the parent module where the subform was created (e.g. Leads) and scroll down there you can view the subform field's API name.

Q. I changed the order of subform records and made a GET - Records API call. The system listed the records in the same order as displayed in the UI, rather than the order of their creation. Is this the system design?

When you make a GET - Records API call for a module, it lists the subform records ordered in the UI. Note that you can re-order the subform records. So, when you retrieve those records via the API, they will be listed in the same order as they are arranged in the UI.

Q. Can we change a subform field's API name via API?

You can change the API name of the subform field only through the UI. Go to Setup -> Developer Hub -> APIs -> CRM API -> API names -> Click on the parent module where the subform was created (e.g. Leads) and go to the Field Label section. There you can view the subform field name and edit the API by clicking on the Edit option.

We trust that this post meets your needs and is helpful. Let us know your thoughts in the comment section or reach out to us at support@zohocrm.com

Stay tuned for more insights in our upcoming Kaizen posts!

------------------------------------------------------------------------------------------------------------------------------

Previous Kaizen Post : Kaizen #123 Data Synchronization from a third party application

-------------------------------------------------------------------------------------------------------------------------------

Cheers!

Additional Reading:

Kaizen Posts:

Kaizen #10 - Search Records API and Query API
Kaizen #31 - Subforms API
Kaizen #80 - COQL API - Part I
Kaizen #81 - COQL API - Part II

Kaizen Series

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