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:





    • Recent Topics

    • Zoho People > Leave Management > Unable to import balance leave

      Hello Zoho I am unable to import balance leave into the system I have follow the steps It show only 5 fields - the date field i am unable to select from date and to date Error Date in excelsheet

    • Narrative 4: Exploring the support channels

      Behind the scenes of a successful ticketing system - BTS Series Narrative 4 - Exploring the support channels Support channels in a ticketing system refer to the various communication methods that customers use to contact a business for assistance. These

    • Tip of the Week #65– Share email drafts with your team for quick feedback.

      Whether you're replying to a tricky customer question or sharing a campaign update, finding the right words—and the right tone—can be tough. You just wish your teammates could take a quick look and give their suggestions before you send it. Sometimes,

    • How to Initiate WhatsApp Message on SalesIQ?

      I've just activated a Business WhatsApp phone number through SalesIQ because of its touted omnichannel chat approach. Sounds exciting. I understand that when a customer sends me a WA message, I can reply to it on SalesIQ and keep the chat going, perfect.

    • Episode IV:Handling User Inputs in custom functions

      Hi Everyone, We've been exploring custom functions which help in performing advanced automation tasks. Custom functions enable you to achieve possibilities based on your organization's requirements. Custom functions require user inputs that allow the

    • Set a lead as non-marketing if they opt out of email marketing

      I'm gathering Lead data via an enquiry form and wish to give them the option to opt out of marketing emails (which we send from Marketing Automation) whilst retaining the ability to send them non-marketing emails - so the email opt-out field doesn't work.

    • Set up multiple IMAP email addresses

      Hi, I just started using CRM and its great, but I just found out I can only add one imap email address for incoming mail in the included salesinbox ...this is ridiculous. All companies have different email such as sales@domain, info@domain , personal@domain

    • Zoho Recruit to Zoho People integration

      In the mapping of field from Zoho Recruit to Zoho People i am unable to map all fields What can i do

    • Zoho Recruit > Career Site > Customisation

      Hi All I have created multiple career site to represent my different organization In my Quanta Media career site > I set it with the with Quanta Malta view In my job opening : Quanta Malta view 2 job opening In my URL for quanta media https://lri.zohorecruit.eu/jobs/Quanta-Malta

    • Formatting Blueprint Stages (buttons)

      Is there a way to format Blueprint transition buttons in Creator like background colour, text colour etc.

    • Disable Default Value in Multi-Select field

      Hello, Is there a way to disable the default value feature when setting up a custom Multi-Select field? When creating tickets I would like it so there isn't a value pre-selected in the multi-select custom field that was created.

    • How to set custom business hours for different teams in Zoho Desk?

      Hi Zoho Team and Community, I’m trying to set different business hours for multiple departments in Zoho Desk. For example, our tech support team works 24/7, while our billing team is only available from 9 AM to 5 PM (Mon–Fri). Is there a way to assign

    • Zia Auto Tag Keyword Clusters

      Is there a way to remove a keyword from a keyword cluster? We're finding that Zia auto-tag is tagging things incorrectly based on some words that don't really make sense.

    • Centralized Domain Verification in Zoho CRM Plus

      Hi Team, I have a suggestion regarding Zoho CRM Plus. It's quite frustrating to verify the same domain separately for each application within the suite. It would be really helpful if you could introduce a centralized admin console—similar to what's available

    • HOw do I make a refund?

      I have a client that needs a refund. I see a refund history in the Report area... but where do I go to make a refund?

    • Creating a work order for dispatch

      We currently uses ZOHO for CRM and Intuit Field Service for creating Work orders and dispatching. This is causing double entry and is not efficient use of time.  I would like to use ZOHO for all customer related activities so can you tell me if you can :  Create a work order that we could manipulate to meet our needs.  Also if you could then dispatch that would be ideal. Thank you

    • "code": "500","description": "Account not exists", mail api

      I have been through all the steps and have a functioning Oath access_token etc etc... I then GET https://mail.zoho.com/api/organization And get my zoid then GET http://mail.zoho.com/api/organization/<hidden>/accounts and get the account details, which

    • Residual Formatting in Text Boxes After Undoing Pasting of Formatted Text

      Hi, guys! I have another problem to report. Actually, I have been aware of this for many months, possibly years, but I have been too lazy to report it to you. My apologies! Let's say you've pasted a formatted string into a text box. You change your mind

    • Feature Request: Stripe Terminal Integration

      I would like to request the addition of Stripe Terminal integration to Zoho Books, which will help process in-person payments. While Zoho Books already supports online payments through Stripe, extending this functionality to include Stripe Terminal would

    • Improved Security in SAML/OIDC Sign-in Redirection Flow

      To enhance the security of our authentication system, we’ve made a change to how SAML and OIDC sign-in redirections are handled. This update resolves a potential open redirection vulnerability and adds an extra layer of protection during the sign-in process.

    • GA4 data

      Hi, I have data being pulled from GA4 into numerous tables. There are a few major errors in the source data. Eg for a period of time GA4 reported ecommerce sales that were $98 as $9,800 and $42 as $4,200. It's not happening now but my historical data

    • Ask the Experts: Five-hour live Q&A session with Zoho WorkDrive product experts

      Have questions about WorkDrive 5.0? Let’s talk! We recently launched Zoho WorkDrive 5.0, packed with powerful updates to help your team work smarter, stay secure, and get more value from your business content. From content-centric workflows and AI-powered

    • Allow the usage of Multi-Select fields as the primary field on "Layout Rules"

      We want to force our users to enter some explanation strings when a multi-select field has been utilized. I can't understand the reason for the usage restriction of Multi-Select fields as a primary field. This is a simple "Display hidden mandatory field

    • Lost Search Box with new UI Design

      I would like to suggest bringing back the Search Box in the new Zoho Project UI.  I use the search feature a lot and having to click the magnifying glass to type for a search is one extra click that we did not have with the old UI.

    • Adaptación de zoho books a la nueva regulación de facturación electrónica

      La facturación electrónica será obligatoria para todas las empresa en España en 2025, en Francia probablemente también e imagino pronto en todos los países europeos. Ya en 2024 todas las empresa grandes tienen que utilizar el sistema de facturación electrónica.

    • ZOHOBOOK Sales_QUOTE: To Add Discount At Each Line Item Table

      Hi, Our quote need to display with discount at each line item level as well. Try to edit template, >CUSTOMISE>EDIT TEMPLATE> Table, I can see template view with discount column, but when hit SAVE the template, view in PDF the discount column not shown.

    • How to account for vat with postponed VAT accounting

      Hi everyone, looking for some help with postponed VAT accounting, I use DHL express for my imports and they used to pay the VAT for me and then invoice me. I could then log this as a bill and the VAT element from import was recorded as input VAT, all

    • Weekly Automation Trigger for Equipment Calibration Reminder

      Dear Team, I’m currently working on an automation in the Equipment module. The goal is to track calibration schedules for tools — all of which require regular calibration. I’ve created an automation that sends email reminders for tools that are due for

    • ADDDATE formula using 2 calculations

      Hello, I want to create an ADDDATE formula using 2 calculations, add 1 month and deduct 1 day. the formula that I need should look like this: ADDDATE(due_date, 1, "Months")+ ADDDATE(due_date, -1, "Days") Each row itself works fine, but when I'm trying

    • Upgrading from Zoho Invoice to Books was a major downgrade in functionality for me

      I have been a user for many years of a free plan on Zoho Invoice for my personal consulting business. I recent upgraded my organization to Books since some of the additional functionality looked useful to me, and played around with the free trial for

    • 🎉 Dynamic Org Chart for Zoho CRM Extension Published [2025]

      Hey Zoho CRM Community! We're thrilled to unveil our latest Zoho extension:🥁 Dynamic Org Chart for Zoho CRM 🎊 This extension is now available to transform the way your teams visualize, manage, and interact with org chart directly inside any Zoho CRM's

    • Detailed General Ledger has problem of exporting out to excel and missing ledger details for some accounts

      I have been encountering some problems generating Detailed General Ledger report with Zoho books. Firstly, I cannot export out the report of Detailed General Ledger to Excel. It will show this error message "invalid value passed for sort column", and

    • Upload a file to a File Upload Field through API

      Hello, Is there any way to upload a file to a custom file upload field in a module when doing an Update using the Record API? I've found and I am able to upload files to attachments but I don't know how to upload them to a field. I've checked the documentation at  https://www.zoho.com/crm/help/api/v2/#update-specify-records but the File Upload field type does not appear in the examples. Thanks

    • Kaizen #131 - Bulk Write for parent-child records using Scala SDK

      Hello and welcome back to this week's Kaizen! Last week, we discussed how to configure and initialize the Zoho CRM Scala SDK. This week, we will be exploring the Bulk Write API and its capabilities. Specifically, we will focus on executing bulk write

    • Automatic pricing feature for sales orders

      I am currently setting up my Zoho Inventory system and would like to implement an automatic pricing feature for sales orders. We have created a custom field called "brandline" for our items. All products with the same brandline value should have the same

    • Ability to access VAT returns and submit them has disappeared.

      I have been using Zoho books successfully to submit quarterly VAT returns. Without reason I have lost that facility. I have followed all available instructions eg going into settings, taxes, VAT etc. without success. My registration number is there and

    • How to automatically schedule a meeting After Blueprint Transition

      As part of our sales process, we require a technician to go to the customer's site and perform an installation prior to advancing to the next stage of the blueprint.  So this will require (a) scheduling a meeting for the technician to visit the customer's site and (b) a reminder phone call the day before the scheduled meeting. As I'm designing the Deal Blueprint, I see that I can automatically add a Task to the deal, but I can't add a Meeting or a Call. What am I missing?  There seem to be 3 types

    • Zoho Recruit > Workflow

      I have created a workflow for my application module Whenever a record is created The condition , application status is 1st call invitation I have set this OI do not receive the email that was suppose to be send out

    • [Webinar] Zoho Writer for SCM and logistics

      Creating, sharing, and distributing complex documents are constant challenges in the SCM and logistics industry. That's why our next webinar is focused on how to simplify these document workflows. Join us on Jul 10, 2025 for a Zoho Writer webinar designed

    • Multiple locations but one parent company

      I am trying to configure my accounts that have multiple locations under one parent company to show separate locations in the portal.   

    • Next Page