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






                    Zoho Campaigns Resources




                          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


                                                          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

                                                                                                          • What's New in Zoho Analytics - October 2025

                                                                                                            Hello Users! We're are back with a fresh set of updates and enhancements to make data analysis faster and more insightful. Take a quick look at what’s new and see how these updates can power up your reports and dashboards. Explore What's New! Extreme

                                                                                                          • Ticket Export Does Not Include Ticket Threads

                                                                                                            Dear Zoho Desk Support Team, I hope you’re doing well. I would like to report an issue regarding the ticket export functionality in Zoho Desk. Currently, when exporting tickets, the ticket threads or conversation history are not included — only the ticket

                                                                                                          • Payments made notification

                                                                                                            This is a really wonderful feature but we can only use it for about 50% of payments made & have to revert to sending statements which is a real chore. Credits applied to the bills paid in the notification aren't included & this causes great confusion in the accounts receivable departments. Please, please add this required feature asap ! .....

                                                                                                          • Ability to add VAT to Retainer Invoices

                                                                                                            Hello, I've had a telephone conversation a month ago with Dinesh on this topic and my request to allow for the addition of VAT on Retainer Invoices.  It's currently not possible to add VAT to Retainer Invoices and it was mutually agreed that there is absolutely no reason why there shouldn't be, especially as TAX LAW makes VAT mandatory on each invoice in Europe!   So basically, what i'm saying is that if you don't allow us to add VAT to Retainer Invoices, than the whole Retainer Invoices becomes

                                                                                                          • ZOHO DESK link with Power BI

                                                                                                            HI, I am using ZOHO Desk for last two years and now my client is asking to integrate ZOHO desk data to Power BI so that they can use Data for reporting. Kindly guide in details so that i can give access to ZOHO desk export data for more visibility.

                                                                                                          • URLs being masked despite disabling tracking

                                                                                                            Hey, We had disabled click tracking from an email update we are sharing with our users. Despite this, the URL the end user is receiving is masked, and looks like "https://qksyl-cmpzourl.maillist-manage.net/click/1d8e72714515cda6/1d8e72714515ca70" instead

                                                                                                          • Zoho CRM - Calendar Cards View - Let Users Decide What Is Displayed On Calendar Entries

                                                                                                            Imagine planning your week of face-to-face meetings across three counties. You’re trying to group appointments by location to make the best use of your time, but Zoho CRM’s calendar doesn’t show where each meeting is happening. You’re left trying to remember

                                                                                                          • Set to Review for all

                                                                                                            We are testing the use of Writer as part of an internal review process for statement of work documents and have found that when the document is changed from Compose to Review by one person, that is not reflected for all others who view the document. Is

                                                                                                          • Dashboard Autorefesh

                                                                                                            Good day, I am a dashboard that displays the number of tickets based on "Product Name". This dashboard is displayed on a big TV for the team to monitor. Can the dashboard auto-refresh every few minutes to display the new values? Currently, we have closed

                                                                                                          • Deferred/ Unearned revenue

                                                                                                            Dear Zoho Team, Just in case you have missed out my query posted few days ago: We issue invoices relating to 12-month web hosting service. When we issue the invoice, we should record the entire amount of the invoice as DEFERRED/UNEARNED REVENUE (ie. $10

                                                                                                          • Report Hover Setting

                                                                                                            Would be great if we will able to show information to the user while hovering a record in a report.

                                                                                                          • Bigin Android app update: Zoho Books integration

                                                                                                            Hello everyone! We’re excited to introduce Zoho Books integration on the latest version(v1.8.5) Bigin Android app. Once the integration is completed in the web(bigin.zoho.com), the Zoho Books tab will be visible in detail View of Contacts, Companies,

                                                                                                          • Audit Log enhancements: Increased retention period, better user visibility, and more

                                                                                                            Hello everyone, The Audit Log brings in the following enhancements which improve the overall ability to manage data. Why did we make these updates? Extended Data Retention: Audit data can now be filtered and exported for a 60-day period, doubling the

                                                                                                          • Question Regarding Managing Sale Items in Zoho Books

                                                                                                            Good day, I was wondering about something. Right now, Zoho Books doesn’t seem to have a way to flag certain items as being on sale. For example, if I want a list of specific items to be on sale from October 1 to October 12, the user would have to export

                                                                                                          • [WEBINAR] Smooth year-end closure with Zoho Books (KENYA)

                                                                                                            Hello there, This webinar is for all Kenyan businesses looking to wrap up their financial year smoothly! Join our free session to learn how Zoho Books can simplify your year-end process. What to expect from this webinar: - All the latest updates in Zoho

                                                                                                          • System flaws and lack of response from Zoho

                                                                                                            I have had to go on here as no-one is replying to my emails regarding my problem (been 10 days and no email reply) and your chat facility online through your Zoho Books software opens and closes immediately, so not functioning properly. I actually called

                                                                                                          • Customer Grouping

                                                                                                            Hi, how can I group multiple customers into single group. So that I can have idea of accounts receivables of all the customers in single group. Like if there are multiple subsidiaries of same company we have having a business with, and want to view the

                                                                                                          • Two currencies

                                                                                                            More and more I am finding that internattional payments' fees are unpredictable. I would like, on my invoices that are in a foreign currency (eg. USD$ or EUR€) for there to be a GBP£ TOTAL display alongside the invoice's currency total. This would make

                                                                                                          • Zoho Books | Product updates | September 2025

                                                                                                            Hello users, We’ve rolled out new features and enhancements in Zoho Books. From PayNow payment method to applying journal credits to invoices and bills in other locations, explore the updates designed to enhance your bookkeeping experience. Integrate

                                                                                                          • GST Slabs Redefined: Stay Compliant Using Zoho Books!

                                                                                                            Hello Everyone! The Government of India is rolling out new GST rates, a major reform aimed at simplifying the current tax structure starting 22 September 2025. GST will move from four slabs (5%, 12%, 18%, 28%) to two main slabs (5% and 18%), plus a special

                                                                                                          • Zoho Books | Product updates | October 2025

                                                                                                            Hello users, We’ve rolled out new features and enhancements in Zoho Books. From iOS 26 updates to viewing reports as charts, explore the updates designed to enhance your bookkeeping experience. Zoho Books Updates for Apple Devices At WWDC 2025, Apple

                                                                                                          • Need Inactive accounts to be visible in Reports in Zoho Books

                                                                                                            I N=need Inactive accounts to be visible in Reports in Zoho Books to do recons of the accounts but when i see the same they are not visible in the Accountant - Account Transactions report

                                                                                                          • Edit item custom fields

                                                                                                            Getting this error : Transactions have been created with the custom field. Hence it cannot be deleted. Not trying to delete it, just trying to change which modules to show in or to not show at all in transactions !

                                                                                                          • Zoho Books - How to Invoke a Custom Function in Schedulers

                                                                                                            We have multiple schedulers that send emails to customers in batches. Currently, we are maintaining the same code across several schedulers. Is it possible to use a custom function inside a scheduler script? If yes, how can we invoke the custom function

                                                                                                          • Use Zoho Books to bill for work done in Zoho Desk??

                                                                                                            I'm trying to see if something is possible (and if yes, how). We use Zoho One to manage our business. We have a lot of clients that will put in a ticket (via portal) to have work done. Out techs will pick up the ticket, do the work, and then log the time

                                                                                                          • Zoho Finance Suite - Customer Custom Tabs - Dynamic Link

                                                                                                            Hi Finance Suite team, When creating a Custom Tab for a Client Portal, there is no option to add dynamic parameters. This would be very helpful for adding Zoho Analytics dashboards which can be dynamically filtered through the URL to only show information

                                                                                                          • Modular Permission Levels

                                                                                                            We need more modular Permissions per module in Books we have 2 use cases that are creating problems We need per module export permission we have a use case where users should be able to view the sales orders but not export it, but they can export other

                                                                                                          • Blueprint or Validation Rules for Invoices in Zoho Books

                                                                                                            Can I implement Blueprint or Validation Rules for Invoices in Zoho Books? Example, use case could be, Agent confirms from client that payment is done, but bank only syncs transactions tomorrow. in this case, Agent can update invoice status to done, and

                                                                                                          • Feature Enhancement Request – Text Formatting Options in Item Description (Zoho Books/Quotes Module)

                                                                                                            Dear Zoho Development Team, Greetings from Radiant360 Integrated Technical Services LLC. We would like to bring to your attention a functional limitation we've encountered within the Item Table / Quote Description section of Zoho Books (and Zoho CRM Quotes).

                                                                                                          • Add Option to Mass Dispatch by User

                                                                                                            Hello! We are using the dispatch console to dispatch service appointments to our service ressources. Right now, the process is our dispatcher verifies each ressource's route for the day and dispatches it after validation. Sadly, there doesn't seem to

                                                                                                          • Bank Receipt Catagorization

                                                                                                            Hi, how can I match a bank deposit to multiple customer's invoices ? For e.g. A single person paid to us on behalf of different five customers. I need to keep the separated invoices for each customer

                                                                                                          • Per Level Approval for admins

                                                                                                            We need Process admins like Zoho CRM in Zoho Books for per stage approval Currently in books, admins only have the option for Final Approval But for example, in cases like when an employee is on leave, we can't just approval one level we only have option

                                                                                                          • Payment on a past due balance

                                                                                                            Scenario: Customer is past due on their account for 4 months. We suspend their billing in Zoho books. Customer finally logs into the portal and enters a new credit card. We associate that cardwith their subscription, which will permit the card to be used

                                                                                                          • How to export all line-item descriptions for a specific item in Zoho Books?

                                                                                                            I am trying to audit a specific item (“Item X”) that has been invoiced multiple times with different line-level descriptions. Here’s the situation: I am using Zoho Books (Professional). Each invoice may contain the same item but with different descriptions

                                                                                                          • List of hidden features

                                                                                                            Hi Friends, I had another support chat today and low and behold the feature that I wanted just simply needed to be "enabled". I thought I'd share, and maybe see if others had some similar experiences. 1. This one is from 5 ish years ago. I asked if there

                                                                                                          • How to change a BAS that has been filed

                                                                                                            I have discovered that a group of expense transactions were accidentally placed in a asset account rather than an expense account. As a result I need to adjust the transaction and consequently most of my BAS to correct the error. Because the BAS have

                                                                                                          • How to Export PDF with a custom Template

                                                                                                            I need to export Sales Order with a Custom Template I have created How can I do it? I see an API to export the PDF but how can I choose which template to choose to generate the PDF

                                                                                                          • Associate email with a potential or project.

                                                                                                            I have a pivotal requirement to associate emails from various suppliers (contacts) with different potentials or projects, on an email by email basis as they come in. This question appears to have been raised before but I cannot find a definitive yes "it can be done". Could anyone please tell me, yes or no.  If the later I can stop wasting time and look at alternative crm systems. I would love not to have to do this. Thanks in advance.

                                                                                                          • MTA - BAD IP reputation by outlook/hotmail

                                                                                                            Messages to Microsoft email servers are bouncing back due to poor reputation. Message: 4.7.650 The mail server [136.143.188.206] has been temporarily rate limited due to IP reputation. For e-mail delivery information see https://postmaster.live.com (S775)

                                                                                                          • Function with Search Records was working until a few weeks ago, around when "Connected Records" was released

                                                                                                            I have a custom function that has been running for nearly a year now, which suddenly stopped working around the time Zoho released the "Connected Records" update. The function is no longer finding the record using the searchRecords function. I've changed

                                                                                                          • Next Page