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.
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
- Insert Subform Records
- Update Subform Records
- Get a Subform
- 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
- Make a Get Modules API call. The response displays the details of all the available modules.
- Search for the module in which you have created the subform. In our case, it is Students.
- Look for the value of the key "generated_type" as "subform".
- 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
- Make a Get Fields Metadata API call to the subform module (crm/v2/settings/fields?module=Languages).
- 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.
- 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
Centralize Knowledge. Transform Learning.
All-in-one knowledge management and training platform for your employees and customers.
New to Zoho Recruit?
Zoho Developer Community
New to Zoho LandingPage?
Zoho LandingPage Resources
New to Zoho Survey?
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Bigin?
Topic Participants
Shylaja S
DataWarehouse
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 thisKaizen #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 howKaizen #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
New to Zoho TeamInbox?
Zoho TeamInbox 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
Design. Discuss. Deliver.
Zoho Show Resources
Get Started. Write Away!
Writer is a powerful online word processor, designed for collaborative work.
Zoho CRM コンテンツ
-
オンラインヘルプ
-
Webセミナー
-
機能活用動画
-
よくある質問
-
Ebook
-
-
Zoho Campaigns
- Zoho サービスのWebセミナー
その他のサービス コンテンツ
Nederlandse Hulpbronnen
ご検討中の方
Recent Topics
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 willZoho 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 newHost 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 linksCan'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?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 OrdersMarketing 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 instructionsPowering 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, leadFunction #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 isLooking 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'dAuto-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 thisZOHO 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 thatSales 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 butHow 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?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 toUpdate 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 fireHow 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?Zoho - Please explain difference between Thread view and Conversation view on Ticket
I have reviewed the help document here but am still not clear on the difference between the two views. As an example, I just had a back and forth on a ticket: - Customer emails support email. - I email back from Desk. - Customer responds back. - I email back from Desk. On the upper left drop down box on the ticket Zoho Desk now says this is "4 Threads" and "4 Conversations" . How is that 4 threads?? By my count it is 1 thread and 4 conversations (assuming by "conversation" Zoho means number of totalI need help to take Reports for tickets moved between departments.
Hi, I need help to take Reports for tickets moved between different departments. Pls guide ShyamExport to excel stored amounts as text instead of numbers or accounting
Good Afternoon, We have a quarterly billing report that we generate from our Requests. It exports to excel. However if we need to add a formula (something as simple as a sum of the column), it doesn't read the dollar amounts because the export storesIncrease Round Robin Scheduler Frequency in Zoho Desk
Dear Zoho Desk Team, We hope this message finds you well. We would like to request an enhancement to the Round Robin Scheduler in Zoho Desk to better address ticket assignment efficiency. Current Behavior At present, the Round Robin Scheduler operatesAutomation #6 - Prevent Re-opening of Closed Tickets
This is a monthly series where we pick some common use cases that have been either discussed or most asked about in our community and explain how they can be achieved using one of the automation capabilities in Zoho Desk. Typically when a customer submitsZoho Desk EU slow/unresponsive
Has anyone else got issues with ZohoDesk today in the EU? It takes an age to come back and if you do start typing something and try and send or save it looks like it times out. We are also getting this pic. ot I can't see anything on https://status.zoho.eu/EU DC Partial Outage Resolved: A Detailed RCA
Incident Summary Due to an overload on one of the nodes in the EU DC for Zoho Desk, the system was unable to handle the heavy load, causing a slowdown in requests and resulting in a partial outage for customers with data residing in that node. On MayPerfomance Management - Zoho People
Hi team, I am looking for performance management data such as KRA, goals, feedback, appraisals, etc., in Zoho Analytics. However, I am unable to find these metrics while editing the setup. Could you please confirm whether these fields are available inDeprecation of the Zoho OAuth connector
Hello everyone, At Zoho, we continuously evaluate our integrations to ensure they meet the highest standards of security, reliability, and compliance. As part of these ongoing efforts, we've made the decision to deprecate the Zoho OAuth default connectorZoho Mail iOS app update: Display recipient's nickname on contact suggestion
Hello everyone! In the most recent version(v3.3.1) of the Zoho Mail iOS app update we have brought in support to display recipient's nickname in contacts suggestion. Please update the app to the latest version directly from the App Store or using theDigest Février - Un résumé de ce qui s'est passé le mois dernier sur Community
Bonjour chers utilisateurs, Le 26 février, nous avons organisé notre première session Ask the Expert de 2026. Nous sommes heureux de partager que ce fut une session très interactive, avec de nombreuses questions intéressantes posées par nos clients. SiZoho CRM Case Notes - Share to Customer
Hi team does anyone know the Api to set a note, against a case, to shared with customer? i cant seem to find it cheersSynching changes to Stripe when changes are made in Zoho Billing
We have a situation where we have merged customers in Zoho BIlling and then found out later that the payment in Stripe was not updated and still associated with the old customer record. The card gets updated and billed, but that payment is still associatedSend out follow-up email in the same thread (threaded conversations in individual emails) from Zoho CRM
Hi, I'm new to Zoho. I'm trying to send individual emails to my leads one by one. And I'll send out follow up email if I don't hear back from them later. However, instead of sending a new email, I want to reply in the same email thread so that the recipientsDepositing funds to account
Hello, I have been using Quickbooks for many years but am considering moving to Zoho Books so I am currently running through various workflows and am working on the Invoicing aspect. In QB, the process is to create an invoice, receive payment and thenweb to lead
Can anyone help me how to create web to lead from zoho marketing automationIntroducing Workqueue: your all-in-one view to manage daily work
Hello all, We’re excited to introduce a major productivity boost to your CRM experience: Workqueue, a dynamic, all-in-one workspace that brings every important sales activity, approval, and follow-up right to your fingertips. What is Workqueue? SalesUI issue with Organize Tabs
When looking at the organize Tabs window (bellow) you can see that some tabs are grayed out. there is also a "Add Module/Web Tab" button. When looking at this screen it's clear that the grayed out tabs can not be removed from the portal user's screenNext Page