Accessing Subform using Zoho CRM APIs

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

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:

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:
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:
Request Method: POST

Sample input to export subform records:
{
    "callback": {
        "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:
{
        . . .
     "query": {
        "module": {
            "api_name": "Project_Details"
        },
        "fields": [
            "Project_Name",
            "Project_Type",
            "Expected_Budget",
            "Status"
        ],
        "criteria": {
            "field": {
                "api_name": "Expected_Budget"
            },
            "comparator": "greater_equal",
            "value": "40000" //Retrieving subform records with an expected budget greater than or equal to $40,000
        }
    }
}


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:





    Access your files securely from anywhere



                          Zoho Developer Community




                                                  • Desk Community Learning Series


                                                  • Digest


                                                  • Functions


                                                  • Meetups


                                                  • Kbase


                                                  • Resources


                                                  • Glossary


                                                  • Desk Marketplace


                                                  • MVP Corner


                                                  • Word of the Day


                                                  • Ask the Experts





                                                            Manage your brands on social media



                                                                  Zoho TeamInbox Resources



                                                                      Zoho CRM Plus Resources

                                                                        Zoho Books Resources


                                                                          Zoho Subscriptions Resources

                                                                            Zoho Projects Resources


                                                                              Zoho Sprints Resources


                                                                                Qntrl Resources


                                                                                  Zoho Creator Resources



                                                                                      Zoho CRM Resources

                                                                                      • CRM Community Learning Series

                                                                                        CRM Community Learning Series


                                                                                      • Kaizen

                                                                                        Kaizen

                                                                                      • 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


                                                                                            Zoho Show Resources


                                                                                              Zoho Writer Writer

                                                                                              Get Started. Write Away!

                                                                                              Writer is a powerful online word processor, designed for collaborative work.

                                                                                                Zoho CRM コンテンツ










                                                                                                  Nederlandse Hulpbronnen


                                                                                                      ご検討中の方




                                                                                                            • Recent Topics

                                                                                                            • Introducing Assemblies and Kits in Zoho Inventory

                                                                                                              Hello customers, We’re excited to share a major revamp to Zoho Inventory that brings both clarity and flexibility to your inventory management experience! Presenting Assemblies and Kits We’re thrilled to introduce Assemblies and Kits, which replaces the
                                                                                                            • Open a popup window from inside Record A and stay on the record after saving Record B

                                                                                                              Hello community, Perhaps you can help me with the following topic. I have a form A with a decision box. When this decision box is checked, a form B pops up. Once Form B is saved, I need to stay on Form A to continue entering data. I've observed the following
                                                                                                            • How to integrate single-sign-on using Linkedin in Zoho Creator

                                                                                                              How to integrate single-sign-on using LinkedIn in Zoho Creator need step by step integration.
                                                                                                            • Stage-Probability Mapping

                                                                                                              How do I answer this question in analytics? What is the Closed-Won percentage of all Deals that reach a given stage? Another way: Of all Deals that reach the Artwork/Price Quote stage, what percentage of them become Closed-Won? I want to populate the
                                                                                                            • Generate a Zoho Sign link

                                                                                                              From time to time I get a response "I never received your you e-document for electronic signature" is there a way to generate a Zoho Sign link to share.
                                                                                                            • What’s New in Zoho Expense: January - March 2025

                                                                                                              Hello users, We're excited to bring you the latest updates and improvements we've made to make your travel and expense management smoother and more effortless. Let's take a quick look at the important updates we've rolled-out in Zoho Expense between January
                                                                                                            • Ask the Experts 19: Live Expert Panel Discussion - Inside Zoho Desk Spring Release 2025

                                                                                                              Hello again! Have you ever needed quick insights into key indicators to help manage and streamline specific operations? Have you started using AI to enhance your customer service in Zoho Desk? From configuring simple bots using Guided Conversations to
                                                                                                            • Onboarding Zoho sign documents?

                                                                                                              I was wondering something about using the Zoho sign integration with the candidate onboarding process. We set up the entire onboarding process and we have added documents that the candidate needs to review and sign digitally using Zoho Sign. This part
                                                                                                            • Creating a whatsapp channel in instant messaging in zoho desk - error Oops, something went wrong. Please try again later.

                                                                                                              Creating a whatsapp channel in instant messaging in zoho desk - error Oops, something went wrong. Please try again later.
                                                                                                            • DKIM record Missing

                                                                                                              zoho says 'DKIM record missing' at the zohomail spf and dkim validation page. dkim record is most certainly in the wix dns settings. anyone had this issue?
                                                                                                            • zohomail - sending faxes via email using thexxxxxx@faxage.com format

                                                                                                              anyone doing this? zohomail - sending faxes via email using thexxxxxx@faxage.com format we do every so often send faxes using faxage.com
                                                                                                            • Permissions on Views

                                                                                                              Having the option of any agent creating custom views is firing back and got a situation where there are a hundred different views across the team and tickets are not being dealt in the most efficient of ways.  Tickets seems to be missed by some agents, whislt others have customized their columns in a way that due dates are not visible and not being respected. There needs to be control on this function in order to have a standard set of views and the ability to prevent users from performing customizations
                                                                                                            • Looking to Hire: Zoho Creator Developer for Vendor Dashboard Portal

                                                                                                              We are a Florida-based licensed liquor distributor using Zoho Books, Inventory, CRM, and Analytics. Many of our vendors are also our customers. We’re looking to build a centralized, secure Vendor Dashboard Portal in Zoho Creator that gives access to real-time
                                                                                                            • What is Resolution Time in Business Hours

                                                                                                              HI, What is the formula used to find the total time spent by an agent on a particular ticket? How is Resolution Time in Business Hours calculated in Zohodesk? As we need to find out the time spent on the ticket's solution by an agent we seek your assistance
                                                                                                            • Repeating Images in Emails

                                                                                                              Some emails have images that are repeated when viewed both on the web client (mail.zoho.com) and when using the Zoho Mail android app. It looks like perhaps some of the email styling is being ignored or applied incorrectly, as a brief inspection of the
                                                                                                            • Why ZOHO Function Can't Read Custom Field API In Quotes Module (Subform)

                                                                                                              I’m using a Deluge function to transfer data from a subform in the Quotes module to a subform in the Accounts module. Everything works except for a custom picklist field in Quotes—no matter what I try, the Zoho API can’t read that field ("Status_sb").
                                                                                                            • Can we customize the default client-facing icons?

                                                                                                              Is there any way to customize the client-facing icons that display in the Zoho Bookings UI?  For example, I'm using the Default page theme and would like to modify the default icon that is shown beside "Service."  The icon currently being shown looks like a baseball hat to me (see attached screenshot) which has no relevance to my business or clients. It would be great if Zoho could provide a different, more generic icon (perhaps a bell icon to represent service?) or better yet allow the icons to
                                                                                                            • Quick Create needs Client Script support

                                                                                                              As per the title. We need client scripts to apply at a Quick Create level. We enforce logic on the form to ensure data quality, automate field values, etc. However, all this is lost when a user attempts a "Quick Create". It is disappointing because, from
                                                                                                            • Many Deals to one Contact - Syncing issue

                                                                                                              Hi, In our CRM we have multiple deals to a contact. We have a field in deals called "Contract Type" - sometimes they are "business" and sometimes they are "personal" deals. I want to be able to send different emails to contacts depending on this field.
                                                                                                            • How to change the default module A"leads" to customised module "abc" in Zoho while integrating the leads from Skrapp!

                                                                                                              How to change the default module A"leads" to customised module "abc" in Zoho while integrating the leads from Skrapp!
                                                                                                            • Zoho Finance Limitations 2.0 #15: You can't filter any Sales Orders by their SubStatus in CRM or Analytics.

                                                                                                              All our sales orders move through various stages and it's nice when you can filter by open orders in "50% Building"  or "100% - Built" however this is not possible in CRM finance. It's a basic feature within native CRM using a picklist. My go to was Analytics,
                                                                                                            • Zoho Payroll's USA and KSA editions are available in Zoho One!

                                                                                                              Greetings! We’re excited to share that Zoho Payroll, currently available only in India and the UAE, is now introducing the KSA (Kingdom of Saudi Arabia) edition and the USA (United States of America) edition, and these editions are now available in Zoho
                                                                                                            • Zoho CRM Forecast - Exclude certain Deals

                                                                                                              We have our forecast and we use it for team forecast/targets/attainment. It works great for that. However, occassionally we have to offer Deals that are non-revenue generating, but are tracked in our CRM. They still have revenue tied to them, but our
                                                                                                            • Por que utilizar o Zoho Creator 6?

                                                                                                              No cenário atual, as empresas enfrentam o desafio constante de adaptar seus processos com agilidade e eficiência. É aí que entra o Zoho Creator 6, a mais recente versão da poderosa plataforma low-code da Zoho — e no nosso novo vídeo, mostramos exatamente
                                                                                                            • Bigin iOS app update - Introducing Card Scanner and initiating WhatsApp conversations using pre-approved templates.

                                                                                                              Hello everyone! In the latest iOS (v1.11.3) version of the Bigin app, we have introduced the following features: Card Scanner Initiating WhatsApp conversations. Card Scanner: Our new Card Scanner feature extracts contact information from business cards.
                                                                                                            • Kaizen #154 - Dynamically Update Picklist Values in Zoho CRM Workflows

                                                                                                              Hello all! Welcome back to another interesting Kaizen post. Today, we will discuss how to add automatically or remove values from a picklist field using Deluge within a workflow. This post serves as a solution for the forum post. Use case The sales team
                                                                                                            • Zoho Bookings <> Oulook

                                                                                                              When a user has their Outlook connected to Bookings should it be able to recognise existing meetings and not give those as available options ? If so, how long is the sync time : ie If i were to put a private meeting at 3pm in my Outlook, how long would
                                                                                                            • Currency Field Does Not show commas upon entry - leading to inaccurate entries!

                                                                                                              Hello Zoho.. When our sales reps are entering deals and the profit/revenue it is difficult to accurately enter numbers with lots of zeros when there commas are NOT added until the record is saved. Could commas be added to this filed type as it is being
                                                                                                            • Anyone get the OpenAI API to work in Zoho Meeting?

                                                                                                              Has anyone been able to get the OpenAI API to work in generating meeting summaries? I have been trying, but I get an error that says "OpenAI key notes request rate exceeded. Please try again later or upgrade your open AI account." I contacted Zoho support
                                                                                                            • m2 is converted to Kader when switching from Dutch to English

                                                                                                              By default, our company works in Dutch. We sell a lot of products with m2 as a unit. Now we've noticed that if we change the language in Zoho to English, the usage unit 'm2' gets replaced by 'Kader'. We've got no idea why. I'd expect that the translation
                                                                                                            • UI and other enhancements in Community module

                                                                                                              Hello everyone, The Community module has undergone a UI revamp to improve user experience. In addition, we have introduced Status Board and Bulk Approval of posts to provide better engagement. Improved User Interface The new interface brings the following
                                                                                                            • Check Validation Rules all fields on Quick Edit on Record Details Page

                                                                                                              I've added validation rules for some fields in a module — let’s say 3 out of 6 fields have rules. On the Edit Page, if any of those fields have an error, I can’t save the form — which is good. But on the Details Page, I can still quick edit other fields
                                                                                                            • E-Invoicing Automation

                                                                                                              Do you have an API endpoint for pushing the invoice through the e-tims for Kenya
                                                                                                            • Easy way to create task from call

                                                                                                              In Bigin I would like to have easy way of creating the tast directly from the call. Now after the call I need to enter company record and create task there. There must be some easier and more user friendly way to create new task after the call!
                                                                                                            • Can we have Backorder Management ?

                                                                                                              Can we have Backorder Management ?
                                                                                                            • Create Funnel to Track Email Outreach Conversion

                                                                                                              Hello, We would like to create a funnel that measures: N° of emails sent -> N° of emails opened -> N° of emails responded We would like to measure this email response conversion rate for each of our SDRs. We use the analytics tool of Zoho CRM and not
                                                                                                            • Performance -> Extend Service -> Forms: How to use created form?

                                                                                                              So I have created a new Annual Evaluation form (cloned from the original one) and now I want to use it in an Appaisal cycle. QUESTION: How can I associate the form with the new Appraisal Template? Also, what is the difference between an Appraiser and
                                                                                                            • Zoho CRM - Rollup Field for "Total Calls TODAY"?

                                                                                                              Good afternoon, I'm trying to build a field that will track the total number of calls made to a lead in one day. This way i can organise my call queues by this to prioritise leads without an attempt. I can put in a Rollup field for *total* calls made
                                                                                                            • Magento 2 as data source for Analytics

                                                                                                              I see that Shopify is in Beta as a data source, any change that Magento 2 is in the works? We currently use Metrilo to parse our eCommerce data for marketing and would love to keep that inside our Zoho ecosystem. Thank you!
                                                                                                            • validation function for Stage QC means QC Done fileupload field not empty on Save

                                                                                                              validation function for Stage QC means QC Done field field not empty . if the fileupload has value also it showing the false statement on save how i fix this Also one more concern is Custom validation function work on blue print transaction. ///this is
                                                                                                            • Next Page