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

                                                                                                                • Is Zoho Sites still actively being developed?

                                                                                                                  Hello, Is Zoho Sites still actively being developed as part of the Zoho ecosystem? I noticed that the What's New page (https://www.zoho.com/sites/whats-new.html) does not show any updates since Q1 2025. We were considering migrating our website from Squarespace

                                                                                                                • Project Notifcatiion Emails - Milestone

                                                                                                                  Hello: I cannot get myself, or most importantly my portal client user to recieve an email upon completion of a milestone. I have set up our 1st project. I have set up a test client user. (accepted the invitation and is listed in the system as a client

                                                                                                                • Zoho Forms - Feature Request - Year Field

                                                                                                                  Hi Zoho Forms Team, You currently have the following date and time fields: Date Time Date and Time Year and Month It would be useful if you could include a "Year" field For example a recent application I completed said "What year was your house built?"

                                                                                                                • Integrate Excel or Zoho Sheet functions / calculations to CRM product module

                                                                                                                  Hello Community, I hope someone more experienced can help me with this question. Our price / payment plan calculations are in an Excel spreadsheet and I would like to use all those functions / calculations in my Products module. So when we send a quote

                                                                                                                • Sync CRM Contacts to USER'S contacts on Office 365

                                                                                                                  I can see that the O365 sync is transferring contacts backwards and forwards between Zoho CRM and Office365. But it has created a separate address book in Office 365 called "Zoho CRM Contacts". This address book is not used by Office/Outlook's email function

                                                                                                                • How can I link Products in a Deal Subform to the Products Module

                                                                                                                  Hello, I have a pricing subform on our Deals page and use a lookup field to associate a product with each line. I want to be able to look at a product page within the Products module and see a list of the deals connected to that product. I have this working

                                                                                                                • Manage Every Customer Conversation from Every Channel inside Zoho SalesIQ

                                                                                                                  Your customers message you from everywhere. But are you really able to track, manage, and follow through on every conversation, without missing anything? With interactions coming in from websites, mobile apps, and messaging platforms like WhatsApp and

                                                                                                                • Zoho Books | Product updates | February 2026

                                                                                                                  Hello users, We’ve rolled out new features and enhancements in Zoho Books. From Advanced Reporting Tags to the ability to mark projects as completed, explore the latest updates designed to improve your bookkeeping experience. Introducing Advanced Reporting

                                                                                                                • Update latitude & longitude address field API

                                                                                                                  How do I update the coordinates of an address field from a widget? I can't modify the latitude and longitude of the address field. I think the problem is how I'm writing formdata variable. zoho_init.then(function (data) { var queryParams = ZOHO.CREATOR.UTIL.getQueryParams();

                                                                                                                • Zoho Forms - Feature Request - Past Into Scanning/OCR Field

                                                                                                                  Hi Zoho Forms Team, You recently introduced the OCR/Scanning field which I have found great use for with one client who receives work orders as a screenshot from one customer. I want to raise a feature request here which would make that field even more

                                                                                                                • inability to use different primary address on invoice per location

                                                                                                                  my company operates in two different locations with different email address. The problems then is the inability to edit the primary to suite the invoice for the second location.

                                                                                                                • Zoho Books - Breaking A Working App

                                                                                                                  We've been using Zoho for many years now. Across all apps, entering phone numbers in standard formats was enabled in all apps. These formats are: xxx.yyy.zzzz xxx-yyy-zzzz (xxx) yyy-zzzz and we were able also to add extension numbers in these formats:

                                                                                                                • No Need To Fix Something That Is Working

                                                                                                                  Zoho Books is a great financial tool which helps businesses to become more efficient and productive with day-to-day operations. As such, every change, upgrade, improvement needs to be carefully thought before implemented in the software and I'm sure Zoho

                                                                                                                • Use Zoho Creator as a source for merge templates in Zoho Writer

                                                                                                                  Hello all! We're excited to share that we've enhanced Zoho Creator's integration with Zoho Writer to make this combination even more powerful. You can now use Zoho Creator as a data source for mail merge templates in Zoho Writer. Making more data from

                                                                                                                • Anyone in Australia using Zoho Books AND has their account with NAB?

                                                                                                                  Hi I have an account with both NAB and Suncorp. Suncorp transaction come in the next day however NAB transactions take 4-5 business days to appear. eg: A deposit made today in my Suncorp will be imported into Zoho tomorrow. A deposit made today to the NAB account will be imported maybe Saturday (Friday overnight). I have contacted both Zoho and NAB but noone seems to know why. I was just wondering if anyone else in Australia uses NAB and has this issue (or doesn't) maybe we could compare notes and

                                                                                                                • Detailed Balance Sheet for tax preparer

                                                                                                                  I'm using the free edition of Zoho Books. My tax preparer is asking for "detailed" Profit & Loss and Balance Sheet reports which include all the activity and transactions within the various categories. The default reports do not include these details.

                                                                                                                • On Edit Validation Blueprint

                                                                                                                  Hello, I have a notes field and a signature field. When the Approve button is clicked, the Signature field will appear and must be filled in. When the Reject button is clicked, the Notes field will appear and must be filled in. Question: Blueprint will

                                                                                                                • Zoho Projects - Cloning a task does not trigger task workflow when created

                                                                                                                  Hello! I have a Project where my team uses a set of tasks from a tasklist as templates, so we could simply clone it and drag it to another list in kanban view to avoid creating a new one from scratch. The process works well, but after cloning it the new

                                                                                                                • Host Group Appointments Online in Zoho Bookings

                                                                                                                  Greetings from the Zoho Bookings team! We’re excited to announce a new enhancement to Group Booking that makes hosting online group events smoother and more professional than ever. You can now conduct online group events with auto-generated meeting links

                                                                                                                • Can't rename groups on Mac desktop app

                                                                                                                  I'm working on an up-to-date Mac with a freshly downloaded Notebook app. I'm trying to rename a group within a notebook. Here I have, left to right, a note, a group, and a note. I select the group. On the top left, I select Action. On the dropdown, "Rename"

                                                                                                                • Workdrive Collaboration with an External User

                                                                                                                  I would like to know if I can setup a collaboration space with an external user in workdrive or do I need to add them as a user on my system? If I need to add them, can I add them on Workdrive only and give limit access to our space only?

                                                                                                                • Delete button

                                                                                                                  Hi, The delete button were hide into the three dot button. Can I display outside? why Zoho make this update?

                                                                                                                • FSM integration with Books

                                                                                                                  Hi, I have spent a few months working with FSM and have come across a critical gap in the functionality, which I find almost shocking....either that, or I am an idiot. The lack of bi-directional sync between Books and FSM on Sales Orders/ Work Orders

                                                                                                                • Marketing Tip #23: Help customers with how-to guides and usage tips

                                                                                                                  Customers don’t stop needing you after they place an order. Helping customers use your product correctly and confidently can improve satisfaction, reduce returns, and increase repeat purchases. Sharing simple how-to guides, usage tips, or care instructions

                                                                                                                • Powering Customer Support with our women

                                                                                                                  In Zoho Desk support, women make up 50% of our team. We see this as one of our strengths, reflecting the spirit of this year’s theme, "Give to Gain". Our women find their balance Women carry many responsibilities — they represent frontline support, lead

                                                                                                                • Function #25: Automatically generate purchase orders from a sales order

                                                                                                                  We kicked off the "Function Fridays" series with the goal of helping you automate your everyday accounting tasks. As we delve into today's post, I'm delighted to announce that we're here to present the 25th custom function in this series. While it is

                                                                                                                • Looking for Guidance on Building a Zoho Website

                                                                                                                  I'm exploring the possibility of building a custom website with specific features using Zoho as an alternative platform. My goal is to create something similar to https://gtasandresapk.com , with the same kind of functionality and user experience. I'd

                                                                                                                • Auto-publish job openings on my Zoho Recruit Careers Website

                                                                                                                  I have developed a script using the Zoho Recruit API that successfully inserts new jobOpening records to my Zoho Recruit website, but my goal is to auto-publish to the Careers Website. The jobOpening field data shows two possible candidates to make this

                                                                                                                • ZOHO Reports are taking longer time to get refresh

                                                                                                                  Hi Team, Since last few days, I'm facing issues in getting updated reports. For eg: right after making an expense entry or even posting a journal, it is taking longer then expected for the updated reports. Refer below: "You are viewing the report that

                                                                                                                • Invalid scope choice: Workdrive integration in CRM

                                                                                                                  Bug: There is an invalid option in the permission choices for Workdrive integration in CRM. If the entry "WorkDrive.teamfolder.CREATE" is selected, it will return a message indicating invalid OAuth scope scope does not exist.

                                                                                                                • Sales IQ chat is not working in signed android apk

                                                                                                                  I have integrated ZOHO sales IQ support chat and i have followed each step and its working fine in my development build but when i create signed APK for it. Chat does not work in it and showing awaiting for detail. I previously asked the same query but

                                                                                                                • How to add line breaks in zoho.cliq.postToUser(...) message?

                                                                                                                  In a CRM function using Deluge I'm sending this message and attempting to add some line breaks but they are ignored. Is there another way to add these breaks? My message: message: New urgent task\nDescription \nThis is a fake description.\n A new line?

                                                                                                                • Enable Free External Collaboration on Notecards in Zoho Notebook

                                                                                                                  Hi Zoho Notebook Team, I would like to suggest a feature enhancement regarding external collaboration in Zoho Notebook. Currently, we can share notes with external users, and they are able to view the content without any issue. However, when these external

                                                                                                                • Problem with CRM Connection not Refreshing Token

                                                                                                                  I've setup a connection with Zoom in the CRM. I'm using this connection to automate some registrations, so my team doesn't have to manually create them in both the CRM and Zoom. Connection works great in my function until the token expires. It does not refresh and I have to manually revoke the connection and connect it again. I've chatted with Zoho about this and after emailing me that it couldn't be done I asked for specifics on why and they responded. "The connection is CRM is not a feature to

                                                                                                                • Update Existing Records greyed out in Free Version

                                                                                                                  Trying to update records from an Excel sheet, and not getting the option to update. Only option is to add as new accounts. All documentation I can see says update should be an option! Accounts, Leads, Contacts, all the same.

                                                                                                                • In Lesson Video

                                                                                                                  Can anyone help me with this? I'm not sure what happened. It suddenly became like that. I tried to reupload. I tried create a new lesson. Still the same. Please help!

                                                                                                                • emailing estimates

                                                                                                                  Shows up in the customer mail logs as sent but nobody is receiving them, even when I send them to myself I don't get them ??? Something wrong with the mail server or my end ?

                                                                                                                • Help with deluge script

                                                                                                                  Hi Community, this is my first Deluge script. I've pieced it together from reading various articles I want to use it in a workflow to 1 Convert a lead to a contact 2. Create a record in a custom module Below is what I have got so far but it does not fire

                                                                                                                • How to use OR when filtering using two fields

                                                                                                                  I want to create return a list of Account Names by filtering on Field1 = "yes" OR Field 2 = "no" I can't see how to use the OR in the filter.

                                                                                                                • Mobile phone version not working well

                                                                                                                  I am working on the Zoho Site Builder. In the preview the desktop version looks okay, but in the mobile phone preview many words are cut off in the weirdest (wrong) way. How can I fix that?

                                                                                                                • Next Page