Kaizen #31 - Subforms #API

Kaizen #31 - Subforms #API

Hello everyone!
Welcome back to another post in the Kaizen series.
In this post, we will discuss the Subform APIs.

What is a Subform?
A subform is a secondary form or a table that enables you to include multiple line items into a primary form. Every line item is a subform record.
Your CRM data are often inter-dependent. Often, you may have the necessity to associate multiple items to a single record. In the technical lingo, we call these "line items".
Consider we have a Students module to store student records. Apart from the data like name, age, date of birth, email ID, courses opted for etc, we may want to have information such as the languages a student knows and the proficiency level in that language. So, Languages can be a subform in the Students module, and Language and Proficiency can be the two fields in that subform.
Therefore, every row in this subform that holds the language and the proficiency is a subform record or a line item.

Here is how the subform looks in a record in the Students module.


To know more about Subforms, refer to Building Subforms.

Note
The Subform API is available only in the Enterprise and Ultimate editions of Zoho CRM.

Let us see how to insert, update, and delete these subform records through the APIs.

Subform APIs
  1. Insert Subform Records
  2. Update Subform Records
  3. Get a Subform
  4. Delete Subform Records

1. Insert Subform Records

You must use the Insert Subform Records API to insert records to a subform while inserting a record to a module.

Details Required: 
      a. API Name of the subform.
      b. API name of the subform fields.

a. API name of the subform
  1. Make a Get Modules API call. The response displays the details of all the available modules.
  2. Search for the module in which you have created the subform. In our case, it is Students.
  3. Look for the value of the key "generated_type" as "subform". 
  4. The value of the key "api_name" gives the API name of the subform. In our case, it is Languages.

b. API name of the subform fields
  1. Make a Get Fields Metadata API call to the subform module (crm/v2/settings/fields?module=Languages).
  2. Search for the field label. The value of the "api_name" key for the fields in the subform are the API names. Here, they are Proficiency and Language.
  3. Note down the "json_type" that represents the type of value the subform fields accept. Here, they are pick lists that accept string values.

To insert subform records:
Request URL: {{api-domain}}/crm/v2/Students
Request method: POST

Sample Input

{
    "data": [
        {
            "Name":"Allan John",
            "Languages1": [
                {
                    "Proficiency": "Native",
                    "Language": "English"
                },
                {
                    "Proficiency": "Professional",
                    "Language": "French"
                }
            ]
        }
    ]
}

Response:


Note
  • A module can have a maximum of two subforms for all editions except Ultimate. The Ultimate edition can have a maximum of five subforms.
  • Every module can have a maximum of 200 subform records with each subform having a maximum of 100 records.
  • A maximum of five aggregate custom fields are available for a subform.
Possible Errors
The "details" key in the response gives you an idea of where the error occurred. This key contains the API name of the field that has incorrect input and other necessary information in other keys.


HTTP Status and Error Code
"details" key
Reason for error
Handling
400 - INVALID_DATA
"details" : {
"api_name":"sub_form_api_name",
"expected_data_type":"jsonarray"
}
Invalid input for subform.

Construct proper subform data and send it in the request body.
400 - INVALID_DATA
"details" : {
"expected_data_type":"data_type",
 "api_name" : "name_of_field",
 "index" : "subform_array_index",
"parent_api_name":"subform_api_name"
}
You have input Invalid data type for the field.
Use parent_api_name, index, and api_name to identify the invalid field and use expected_data_type to construct a proper value.
400 - INVALID_DATA
"details" : {
 "api_name" : "subform_api_name",
 "info" : "Maximum of 100 records allowed"
}
A subform can only have a maximum of 100 records.
Do not associate further records to the mentioned subform.

2. Update Subform Records

Now that we have created a subform, every subform row is a record with a unique ID. 
Use the Update Subform Records API to update the subform record(s).

Let us now update the subform entries we just added to the Languages subform in the Students module.
The changes we are making are:
      a. Adding a subform entry for the Language "Spanish" with Proficiency as "Professional".
      b. Updating the Proficiency of the Language "French" to "Native".

Details required:
Record IDs of the subform records that you want to update. Make a Get Subform Data API call to the Student record you want to update the subform in.



The request to update the subform is
Request URL: {{api-domain}}/crm/v2/Students/3652397000002125005
Request method: PUT

Sample Input

{
    "data": [
        {
            "Languages": [
                {
                    "Proficiency": "Professional", //new subfrom record
                    "Language": "Spanish"
                },
                {
                    "id":"3652397000002125020",  //ID of the subform record that you want to update
                    "Proficiency": "Native",
                    "Language": "French"
                },
                {
                   "id":"3652397000002125019" //ID of the subform record that does not need any change
                }
            ]
        }
    ]
}

Response:



Note
  • You must specify the record IDs of the subform records you want to update and also the ones you do not want to update.
  • If you do not specify their IDs, the system deletes those records from the subform.

Possible Errors

HTTP Status and Error Code
"details" key
Reason for error
Handling
400 - INVALID_DATA
"details" : {
"api_name":"sub_form_api_name",
"expected_data_type":"jsonarray"
}
Invalid input for subform.
Construct proper subform data and send it in the request body.
400 - INVALID_DATA
"details" : {
"expected_data_type":"data_type",
 "api_name" : "name_of_field",
 "index" : "subform_array_index",
"parent_api_name":"subform_api_name"
}

You have input invalid data type for the field.
Use parent_api_name, index, and api_name to identify the invalid field and use expected_data_type to construct a proper value.
202- INVALID_DATA
Message: the id given seems to be invalid
1. Either the record ID or the subform record ID is invalid, (or)
2. User does not have the permission to the mentioned record.
1. Check the record ID sent in the API request URL or in the request body (or)
2. Check the subform record ID sent in the request body.

3. Get a Subform

You can use the Get Subform Data API to fetch the details of the subform of a record.
In the response, the key Parent_Id gives the name and ID of the record that the subform record is associated to.

Request URL: {{api-domain}}/crm/v2/Languages
Request method: GET

Response:



You can also get the subform details when you fetch a record from the module the subform is created in.

Request URL: {{api-domain}}/crm/v2/Students/3652397000002125005
Request method: GET

The response is as below.



4. Delete Subform Records

Simply make an Update Subform Records API call to the record whose subform record you want to delete.
Specify only the IDs of the subform records that you want to retain. The system deletes the other subform records whose IDs you have not specified.


We hope you found this post useful. Stay tuned for more!

Write to us at support@zohocrm.com if you have any questions, or let us know in the comment section.

Cheers!













    Access your files securely from anywhere

        All-in-one knowledge management and training platform for your employees and customers.






                              Zoho Developer Community



                                  Bootcamp
                                  Community
                                  Pricing
                                  Webinars
                                  What's New
                                  Integrations
                                  Contact Support
                                  Contact Sales
                                    Zoho Survey Resources
                                      Features
                                      Survey Templates
                                      Integrations
                                      Community
                                      iOS Mobile Surveys
                                      Pricing
                                      Android Mobile Surveys
                                      Insurvey Blogs
                                      Insight Blogs
                                      Tips & Tricks





                                                  Latest Feature Updates

                                                    • Desk Community Learning Series


                                                    • Digest


                                                    • Functions


                                                    • Meetups


                                                    • Kbase


                                                    • Resources


                                                    • Glossary


                                                    • Desk Marketplace


                                                    • MVP Corner


                                                    • Word of the Day


                                                    • Ask the Experts




                                                        Zoho SalesIQ Resources

                                                              • 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


                                                              Manage your brands on social media
                                                              Access Zoho Social

                                                                Zoho Pagesense Resources


                                                                    Zoho TeamInbox Resources

                                                                      Zoho DataPrep Resources


                                                                        Zoho CRM Plus Resources

                                                                          Zoho Books Resources


                                                                            Zoho Subscriptions Resources

                                                                              Zoho Projects Resources


                                                                                Zoho Sprints Resources


                                                                                  Qntrl Resources


                                                                                    Zoho Creator Resources



                                                                                        Zoho 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

                                                                                                Get Started. Write Away!

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

                                                                                                  Zoho CRM コンテンツ




                                                                                                    Nederlandse Hulpbronnen


                                                                                                        ご検討中の方




                                                                                                                • Recent Topics

                                                                                                                • AI Search and Record Retrieval Inside Zoho Creator – Is This Possible?

                                                                                                                  Is it possible to integrate an AI assistant into Zoho Creator that can intelligently search, retrieve, and analyze records within the application’s forms and reports? Can AI access and query existing Creator data securely using Deluge or APIs to provide

                                                                                                                • I have a requirement to integrate Zoho Books with Zoho Projects at both project and task levels.

                                                                                                                  Currently, when i create transactions in Zoho Books (Expenses, Invoices, Bills), we can only map them at the project level. However, our requirement is to: Map records at both project and task levels Sync these transactions back to Zoho Projects under

                                                                                                                • Scheduled AU Data Center Database Version Upgrade for Zoho Forms

                                                                                                                  Dear Zoho Forms' users, We would like to update you on a scheduled AU Data Center database version upgrade for Zoho Forms. Find the schedule below: Migration window: Sunday, 22nd February 2026 12.00 AM to 12.30 AM AEDT This migration is a part of our

                                                                                                                • Cannot get code to work with v2.mergeAndStore!

                                                                                                                  Please can someone help me pass subform items into a repeating mail merge table row using v2.mergeAndStore? I have a mail merge template created in Writer and stored in Workdrive. This template is referenced by a custom CRM function which merges all of

                                                                                                                • Hotmail is blocking the zoho mail IP

                                                                                                                  Greetings, Since last Tuesday (5 days ago today) I wrote to Zoho support and I still haven't received a single response (Ticket ID: 2056917). Is this how you treat people who pay for your email service? I am making this public so that those who want to

                                                                                                                • Zoho Bookings and Survey Integration through Flow

                                                                                                                  I am trying to set up flows where once an appointment is marked as completed in Zoho Bookings, the applicable survey form would be sent to the customer. Problem is, I cannot customise flows wherein if Consultation A is completed, Survey Form A would be

                                                                                                                • Zoho CRM Community Digest - December 2025 | Part 2

                                                                                                                  Hello Everyone! During the final weeks of December, Zoho CRM introduced updates that not only enhanced product capabilities but also offered deeper guidance through Kaizen posts. This section highlights what was released and shared in the last two weeks

                                                                                                                • CRUD actions for Resources via API

                                                                                                                  Hello, is it possible to perform CRUD actions through the API for Resources? We want to create a sync from Zoho CRM Car record to Bookings resources to create availabilities for Car bookings. For Test drives, not only the sales person needs to be available,

                                                                                                                • Kaizen #186 : Client Script Support for Subforms

                                                                                                                  Hello everyone! Welcome back to another exciting Kaizen post on Client Script! In this edition, we’re taking a closer look at Client Script Support for Subforms with the help of the following scenario. " Zylker, a manufacturing company, uses the "Orders"

                                                                                                                • オンライン勉強会のお知らせ Zoho ワークアウト （2/19 参加無料）

                                                                                                                  ユーザーの皆さま、こんにちは。コミュニティチームの中野です。 2月開催のZoho ワークアウトについてお知らせします。 今回はZoomにて、オンライン開催します。 ▶︎参加登録はこちら（無料） https://us02web.zoom.us/meeting/register/6AyVUxp6QDmMQiDGXGkxPA ━━━━━━━━━━━━━━━━━━━━━━━━ Zoho ワークアウトとは？ Zoho ユーザー同士で交流しながら、サービスに関する疑問や不明点の解消を目指すイベント「Zoho

                                                                                                                • doubts about customer happiness in zoho desk

                                                                                                                  Good afternoon, Desk community. The reason for my message is that I have a question regarding the customer satisfaction surveys we can ask our clients to rate our service. I know that in Desk, you can activate Customer Happiness to send a survey to the

                                                                                                                • COQL API in JS Widget only pulling 200 records

                                                                                                                  Hello! We've been building a custom homepage widget using the Zoho JS SDK, and it seems that this https://help.zwidgets.com/help/latest/ZOHO.CRM.API.html#.coql only allows 200 records. I thought the limit was 2000 for COQL queries, but am I mistaken?

                                                                                                                • Standard Description Field - Can I change label or add dd tooltip

                                                                                                                  Is there a way fo you guys to allow the customer to change the label name for the description field in the customer portal when submitting tickets. Or at least allow us to add a tooltip to clarify what description we need from them. I know I can create my own separate multi line description field but if I do that, it doesn't have the nice toolbar with Bold, Italic, Underline, color, font, indent, etc. Can you please allow us to add a tooltip to the zoho standard description field?

                                                                                                                • Compensation | Salary Packages - Hourly Wage Needed

                                                                                                                  The US Bureau of Labor Statistics says 55.7% of all workers in the US are paid by the hour. I don't know how that compares to the rest of the world, but I would think that this alone would justify the need for having an hourly-based salary package option.

                                                                                                                • Customizing Helpcenter texts

                                                                                                                  I’m customizing the Zoho Desk Help Center and I’d like to change the wording of the standard widgets – for example, the text in the “Submit Ticket” banner that appears in the footer, or other built-in widget labels and messages. So far, I haven’t found

                                                                                                                • Ability to Edit Ticket Subject when Splitting a Ticket

                                                                                                                  Often someone will make an additional or new request within an existing ticket that requires we split the ticket. The annoying part is that the new ticket maintains the subject of the original ticket after the split so when the new ticket email notification

                                                                                                                • Automatically Update Form Attachment Service with Newly added Fields

                                                                                                                  Hi, When I have a Form Setup and connected to a 3rd Party Service such as OneDrive for Form Attachments, when I later add a new Upload Field I have to remove and redo the entire 3rd Party Setup from scratch. This needs to be improved, such as when new

                                                                                                                • Unable to produce monthly P&L reports for previous years

                                                                                                                  My company just migrated to Books this year. We have 5+ years financial data and need to generate a monthly P&L for 2019 and a monthly P&L YTD for 2020. The latter is easy, but I'm VERY surprised to learn that default reports in Zoho Books cannot create

                                                                                                                • Reopen ticket on specific date/time

                                                                                                                  Is there a way that we can close a ticket and setup a reopen of that ticket on a specific date and time? (without using the "on hold" ticket option)

                                                                                                                • API credit COQL COUNT

                                                                                                                  The docs describe API credits in COQL from the LIMIT perspective: https://www.zoho.com/crm/developer/docs/api/v8/COQL-Overview.html When using aggregate functions such as `COUNT` or `SUM`, is that billed as 1 API credit?

                                                                                                                • Anyone Building AI-Based SEO Dashboards in Zoho Analytics?

                                                                                                                  Hey everyone, I’m currently working on an SEO reporting dashboard in Zoho Analytics and looking to enhance it with AI-based insights—especially around AI visibility, keyword trends, and traffic sources. The goal is to track not just traditional metrics

                                                                                                                • Remove 'This is an automated mail from Zoho Sign' in footer

                                                                                                                  Hi there, Is it possible to remove or change the text under the e-mail templates? I can't figure out how to do that: Would love to hear from you. Kind regards, Tristan

                                                                                                                • Passing Info from Function to Client Script

                                                                                                                  Hello, I have recently started making use of client script for buttons, allowing me to give the user information or warnings before they proceed. This is great. However, I have never quite managed to pass back any extra information from the function to

                                                                                                                • Drag 'n' Drop Fields to a Sub-Form and "Move Field To" Option

                                                                                                                  Hi, I would like to be able to move fields from the Main Page to a Sub-Form or from a Sub-Form to either the Main Page or another Sub-Form. Today if you change the design you have to delete and recreate every field, not just move them. Would be nice to

                                                                                                                • Zoho Payroll for Canada

                                                                                                                  Is anyone else having problems getting setup for Canada?

                                                                                                                • Passing the CRM

                                                                                                                  Hi, I am hoping someone can help. I have a zoho form that has a CRM lookup field. I was hoping to send this to my publicly to clients via a text message and the form then attaches the signed form back to the custom module. This work absolutely fine when

                                                                                                                • One Contact with Multiple Accounts with Portal enabled

                                                                                                                  I have a contact that manages different accounts, so he needs to see the invoices of all the companies he manage in Portal but I found it not possible.. any idea? I tried to set different customers with the same email contact with the portal enabled and

                                                                                                                • User Automation: User based workflow rules & webhooks

                                                                                                                  User management is an undeniable part of project management and requires adequate monitoring. As teams grow and projects multiply, manual coordination for updating users & permissions becomes difficult and can give way to errors. User automation in Zoho

                                                                                                                • Default Ticket View - Table?

                                                                                                                  Guys, We mostly use the table view to queue tickets. Maybe I am missing it - but how can I set that view as 'default" for all our agents? Thanks JV

                                                                                                                • Zoho One IS BUGGY

                                                                                                                  Here are some things that just don't work: - Disabling applications from certain Spaces - Adding users (probably only for me) - Renaming applications in Zoho One Portal (fixed by now) - Reordering applications in Spaces When I try to reorder: It feels

                                                                                                                • Merge Fields that previously worked are now giving an Error!

                                                                                                                  Saving a URL Link button on the Deal module. The below fields used to save without issue at all, but now produce an error of "URL contains unsupported merge field!" ${Contacts.Mailing Street} ${Contacts.Mailing City} ${Contacts.Mailing State} ${Contacts.Mailing

                                                                                                                • Clarification on Zoho Forms 1-User Plan: Multiple Submitters and Approvers

                                                                                                                  Question Content (Copy–Paste Ready) Hello Zoho Team, I would like clarification regarding Zoho Forms pricing and user limits. I am planning to subscribe to the ₹700/month (1 user) plan. My use case is as follows: Only 1 person (myself) will create and

                                                                                                                • App for Mac OS X please!

                                                                                                                  It would be awesome to have a mail app for Mac OS X that included all the cool features such as steams, calendar, tasks, contacts, etc. Most people prefer native apps, rather than running it through a web browser. I know that we can use the IMAP, CalDAV,

                                                                                                                • Facing Issues with Sites Mobile font sizes

                                                                                                                  my page renediaz.com is facing issues mobile view, when i try to lower font sizes in home page, instead of changing the size, it changes the line space

                                                                                                                • Zoho Books Payroll

                                                                                                                  How am I supposed to do payroll and pay my employees with Zoho Books? I think it's pretty strange that an accounting software doesn't have the ability to perform one of the most common functions in business; paying your employees. Am I missing something,

                                                                                                                • Canvas templates can now be shared with different CRM organizations

                                                                                                                  ----------------------------------------Moderated on 14th February, 2023------------------------------------------- Dear all, This feature is now open for all users in all DCs. To learn more about importing and exporting canvas templates, read our help

                                                                                                                • Change Last Name to not required in Leads

                                                                                                                  I would like to upload 500 target companies as leads but I don't yet have contact people for them. Can you enable the option for me to turn this requirement off to need a Second Name? Moderation update (10-Jun-23): As we explore potential solutions for

                                                                                                                • creating an alias

                                                                                                                  your instructions for creating an alias are wrong. there is no add alias in my mail account. also i dont have a control panel link just a settings link how do i really make an alias

                                                                                                                • Reply to Email for SO/PO

                                                                                                                  Hello, We are new to Zoho Books and running into an issue. Our support@ email is our integration user. When our team is sending out PO/SO's we are updating the sender email, but for some reason many of our responses are coming back to our support@ email

                                                                                                                • ZOHO Payroll Canada

                                                                                                                  Any plans on the roadmap for Canada?

                                                                                                                • Next Page