Kaizen #124 - Manipulating Subform using Zoho CRM APIs

Kaizen #124 - Manipulating 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:





    • Sticky Posts

    • Kaizen #198: Using Client Script for Custom Validation in Blueprint

      Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

    • Kaizen #226: Using ZRC in Client Script

      Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In this

    • Kaizen #222 - Client Script Support for Notes Related List

      Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore how

    • Kaizen #217 - Actions APIs : Tasks

      Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.

    • Kaizen #216 - Actions APIs : Email Notifications

      Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are

      • Recent Topics

      • Allow Global Admin to access/edit all forms without changing owners

        Hi there, Please consider adding a feature where the Global Admin of the account an automatically access/edit any form in the Company Account. I'm the Global Admin on our Zoho One plan, and we have multiple users that use/create forms. But for me to access

      • ERROR: "Please enter a valid Phone"

        WHAT IS THE PHONE FORMAT? There is nothing ANYWHERE to define the format. At least the error should either show the correct format or provide a link to the help file I enter a valid phone number in as many formats as I can think of and none of them allow me to save the number to CRM Nothing works! No matter what format I enter I keep getting a red error "Please enter a valid Phone" The international format for MY mobile is +61414652366 (or +61 414 652 366) Local format is 0414652366 I call all over

      • Introducing Zoho Sprints 3.0

        Zoho Sprints is consistently evolving in steady increments. The introduction of the latest version, with its enterprise level solutions, brings to you advanced capabilities that propel your agile efforts in the right direction. Here's a quick glimpse

      • Transaction Rules & Customer Payments

        So I have a situation as follows. We have many clients who are all invoiced on the 1st of each month on a recurring invoice for 1 of 10 plans. This means that almost all payment dates are the same (some people pay late) and that a lot of the amounts are

      • Customize Sign-out Button

        Are there some url parameters I can use to make a form button sign-out the user from the app? The sign-out link on the top right is small. Here's and example of the url for the top right sign-out: https://creator.zoho.com/logoutpage.jsp?sharedBy=niskypto&appID=212085000006568003&appLinkName=MYAPP&signOutUrl=niskypto/MYAPP/view-login/SOMEPAGE Note: In my account, the sign-out is set to redirect users to my website. Can I also override this with some url parameters? John M. Whitney

      • Please can the open tasks be shown in each customer account at the top.

        Hi there This has happened before, where the open tasks are no longer visible at the top of the page for each customer in the CRM. They have gone missing previously and were reinstated when I asked so I think it's just after an update that this feature

      • Tip #65 - Exploring Technician Console: Short Keys - 'Insider Insights'

        Hello Zoho Assist Community! Have you ever been in the middle of a remote support session, trying to pass a key combination onto the remote machine, only to find it's reflecting on the technician's computer. The Short Keys feature in Zoho Assist is here

      • Reading from and writing to Zoho Projects Custom Module with Deluge

        Does anyone know if there is a way to read from and write to the Custom Modules that Zoho now supports. I would love to be able to loop through a set of data and create the entities I need to for this new custom module I'm looking to put together.

      • Disappointment with Zoho Payments

        Dear Gowdhaman, I am writing to inform you that I am removing Zoho Payments from my website. I cannot continue to disappoint my customers due to the lack of UPI support, as has been the case with my experience so far. Please note that the 0.5% transaction

      • Evolução do modelo de ambientes: Dev, Homologação e Produção com pacotes versionados

        Hoje o Zoho CRM já oferece Sandbox, o que é um avanço importante para organizações que trabalham com customizações mais complexas. No entanto, na prática, o modelo atual ainda apresenta limitações significativas quando múltiplas equipes ou consultorias

      • Permissões granulares por usuário além do modelo baseado exclusivamente em perfis

        Atualmente, o modelo de segurança do Zoho CRM é fortemente baseado em perfis. Embora funcional, esse modelo apresenta limitações quando equipes possuem variações individuais de acesso dentro do mesmo grupo operacional. Em cenários reais, é comum que usuários

      • Add or update lookup field values during Blueprint transition

        Hello everyone, During blueprint transition users can add or modify the value of a lookup field. For instance, if the Tickets module includes a lookup field that connects it to records in the Assets module, agents can link the ticket to the correct asset

      • Can you limit SEO penalties by delaying the appearance of a pop-up?

        Google is not keen on pop-ups and has got even less keen on them with the new Core Web Vitals updates. But I like using pop-ups. If you delay the pop-up so it only appears 10 seconds after the page loads, do you avoid Google’s penalties? 

      • Adding bank details to the contact through API

        How to add bank-related information to the contact while creating it using API? The account number needs to be encrypted before sending it through API but not sure how to encrypt and get those values. Please guide me in this.

      • Restrict Payment Methods

        Allow us to restrict certain payment methods specific for each customer.

      • Clone Banking Transaction

        Why is there no option to CLONE a Transaction in the Banking module?? I often clone Expenses (for similar expense transactions each month) so I would also like to clone Income transactions. But there is no option in Banking to clone an existing Income

      • PDF limit

        Hello everyone, We have received an e-mail that we have reached our PDF limit. (see screenshot) However, I cannot find any reference to a PDF limit in our tariff plan (Premium). (see screenshot). What is the maximum number of PDFs that can be generated

      • How can I see content of system generated mails from zBooks?

        System generated mails for offers or invices appear in the mail tab of the designated customer. How can I view the content? It also doesn't appear in zMail sent folder.

      • Credit Card Pre-Authorization with later Capture/Settlement

        We really enjoy the convenience of being able to pay off a customer's invoice using our Auth.Net integration with Zoho Books. Unfortunately, we can only take advantage of this feature with a small percentage of our customers as it leaves a gaping hole

      • Zoho Projects and CRM Integration in Analytics

        Hi Team, In Zoho CRM, I’ve integrated CRM with Zoho Projects and associated a project within the CRM. The integration is visible under the Deals module. However, I’m unable to find this data in Zoho Analytics. Does anyone know where this information is

      • Accessibility in Zoho CRM: Not just a feature—a way to empower

        For instructions on setting up these controls, please check this help document: Configuring accessibility controls. Hello everyone, Today (December 3, 2024), on the International Day of Persons with Disabilities, we begin our journey towards a CRM that

      • Automation Series #1: Round Robin vs Direct Assignment in Zoho Desk

        Direct Assignment vs Round Robin: Choosing the right routing method in Zoho Desk This post is part of the "Desk Automation Series," Chapter 1. Through this series, we will help you choose the right automation type in Zoho Desk by comparing commonly confused

      • Invalid tax authority ID.

        How do I correct this ?

      • Pay Pal Paylater button

        I am testing the paypal setup to have my customers pay invoices with paypal and credit cards. But it seems to have two options. Paypal and Pay later. I don't want my customers access to pay later feature. How can I turn that part off.. My other integration

      • Zoho Workshops are coming to the Netherlands - Join us on 14-16 April in Amsterdam!

        Dear Zoho Community Members, After succesful recent editions in the UK and Scandinavia, we’re pleased to invite you to the upcoming Zoho Benelux Workshop 2026, taking place 14–16 April 2026 in Amsterdam. This three-day, in-person event at the Park Plaza

      • How to install Widget in inventory module

        Hi， I am trying to install a app into Sales Order Module related list, however there is no button allow me to do that. May I ask how to install widget to inventory module related list?

      • Sub form auto field population based on parent form

        I have a parent form called "Sites" with a text field called "Site". I have a subform called "Design Comments" (actual form name "Review Comments") with a lookup field name "Sites1" that looks up from the Sites form. I want the Sites1 lookup field to

      • Building Toppings #7 - Using schedules and workflow functions

        Hello Biginners, In our previous forum post, we explored install and uninstall actions and learned how to trigger custom logic the moment a topping is added or removed from an organization. In this post, we'll look at how to automate actions during regular,

      • Simplify scripting with Zia assistant bot

        Hello everyone, Building automation using Deluge custom functions gives users flexibility and control. Traditionally, creating these functions required writing scripts, testing the logic, and validating the configuration before using it. With Zia assistant

      • Zoho Sprints iOS app update: Global view, screen capture control, file encryption, tags enhancement

        Hello everyone! We are excited to introduce new features in the latest version(v2.1) of the Zoho Sprints iOS app update. Let’s take a quick look at what’s new. 1. Global view Global view brings all your project items into one centralised space. You can

      • Resource Management System built using Zoho CRM, Creator, Projects, and People:

        In a Resource Management System built using Zoho CRM, Creator, Projects, and People: CRM Deal Closed → Creator Allocation Engine → Zoho Projects Task Assignment What is the recommended architecture to handle dynamic reassignment when: an employee goes

      • Request to Remove LinkedIn Verification from My Emai

        I would like to submit a complaint regarding my Zoho Mail account. I previously used this email address to verify a LinkedIn account, but that LinkedIn account has now been closed. I need to remove or cancel the verification associated with the closed

      • Pin multiple columns and adjust column widths in CRM subforms

        Hello all, Subforms act as secondary forms or tables in which you can associate multiple line items to a primary record and thereby ensure more structured and comprehensive data organization. We've made some recent enhancements to subforms. Here's what's

      • Removing To or CC Addresses from Desk Ticket

        I was hoping i could find a way to remove unnecessary email addresses from tickets submitted via email. For example, a customer may email the support address AND others who are in the helpdesk notification group, in either the TO or CC address. This results

      • From Zoho CRM to Paper : Design & Print Data Directly using Canvas Print View

        Hello Everyone, We are excited to announce a new addition to your Canvas in Zoho CRM - Print View. Canvas print view helps you transform your custom CRM layouts into print-ready documents, so you can bring your digital data to the physical world with

      • Announcing Kiosk 1.1 - Customize screen titles, configure new fields & actions, use values from your Kiosk to update fields, and more.

        Hello all We are back again with more enhancements to Kiosk. So what's new? Enhancements made to the Components Add titles for your Kiosk screens and adjust its width to suit your viewing preferences. Three new fields can be added to your screen: Percentage,

      • CRM Percent custom fields: When will it show the % symbol and behave like %?

        1. Actually Percent custom fields fail to show the % symbol. 2. When in formulas Percent fields work like number: 100 x 5% = 5 ideal world 100 x 5% = 500 what happens actually 3. When importing Percent fields the % symbol has to be removed and the data

      • Introducing Color Coding of Picklist Values

        Dear Everyone, Greetings!! Zoho CRM is uplifting the user experience. Recently, we had some notable aesthetic improvements in CRM like Kanban View UI enhancement, New List view UI enhancement, color coding of tags, and color coding of picklists in meetings.

      • Where can I find the best mail backup tool for Windows?

        Later this evening I found Mail Backup Tool in google. Actually I was looking for a solution to download/save emails to my local drive. As I had plenty of important data stored in my email account. So i was not in a mood to take this thing lightly. This made me curious to found any software which can help me to backup my data to hard drive. Then I found the above application which was like a gem. A complete email backup solution for Zoho Mail, Gmail, Yahoo Mail, Office 365 and more than 40+ email

      • Mailbox storage showing incorrect usage

        My mailbox shows 4.99 GB used out of 5 GB. However, actual mailbox usage is only around 394 MB. Trash and Spam are already empty. IMAP/POP is not enabled. WorkDrive is not in use. This appears to be a storage calculation issue. Please help to recalculate

      • Next Page