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
Possible to Turn Off Automatic Notifications for Approvals?
Hello, This is another question regarding the approval process. First a bit of background: Each of our accounts is assigned a rank based on potential sales. In Zoho, the account rank field is a drop-down with the 5 rank levels and is located on the accountWill be possible to create a merge mail template for products?
Hi, we would need to create a mail merge template for products (native) module. Will be possibile? or do you have a smart solutions to merge products data with a mail merge? thanks ChrisMaximum incoming email (attachment size) limit
I see that the maximum size of received emails can now be set to 20MB, however I'd still like to see it be larger. It's embarrassing when a client sends me an email with a large attachment and I can't receive it. 50, even 100 MB seems reasonable these[Free Webinar] Learning Table Series - Multi-currency management in Zoho Creator
Hello everyone, We’re excited to invite you to another edition of the Learning Table Series webinar. As you may already know, we've moved to a purpose-based approach in the Learning Table Series this year. Each session now focuses on how a Zoho CreatorOutlook/Hotmail Blocking Zoho SMTP IPs (S3150)
We are currently facing a serious deliverability issue with Zoho SMTP while sending transactional OTP emails for our production application. Emails sent to Outlook / Hotmail addresses are being rejected with the following error: 550 - 5.7.1 Unfortunately,Outlook is blocking incoming mail
Outlook is blocking all emails sent from the Zoho server. ERROR CODE :550 - 5.7.1 Unfortunately, messages from [136.143.169.51] weren't sent. Please contact your Internet service provider since part of their network is on our block list (S3150). It looksLESS_THAN_MIN_OCCURANCE - code 2945
Hi I'm trying to post a customer record to creator API and getting this error message. So cryptic. Can someone please help? Thanks VarunRanking by group in report
Dears, I am new to Zoho Analytics and I would like to ask you guys help to creating a ranking column. Report type: Pivot Matter: I want to create a ranking column on the right of Percentage. This ranking is group by column Type, and ranking by Final Score/Percent.How do I add a project template to a pre-existing project?
Help....How do I add a project template to a pre-existing project? Right now I have to delete the old project, make a new one and add the project template at the time of creating the new project.Passing the image/file uploaded in form to openai api
I'm trying to use the OpenAI's new vision feature where we can send image through Api. What I want is the user to upload an image in the form and send this image to OpenAI. But I can't access this image properly in deluge script. There are also some constraintsUsers may not pick the fields to be shown as columns in the Choose Account window when creating a new Deal record
Hi there, by talking with other users I found out that I, as an Admin, am the only one who can pick fields to be shown as columns in the Choose Account window when creating a new Deal record. In fact, if other users click on the "Add Column" symbol on{Action Required} Re-authenticate your Google Accounts to Continue Data Sync
Hello Users! To align with Google’s latest updates on how apps access files in Google Drive, we’ve enhanced our integration to comply with the updated security and privacy standards, ensuring safer and more reliable access to your data. With this update,Why is the ability Customize Calls module so limited?
Why can't I add additional sections? why can't I add other field types than the very limited subset that zoho allows? Why can I only add fields to the outbound/inbound call sections and not to the Call Information section?Report Template - How to remove page break after each record?
Hi, We have report template for a list report. It looks good at screen. But when printing, it creates a page break after each record. How to remove the it? So we can print multiple records in same page. Please look at the attached screenshots. Report Template Report Print PreviewCalendar report with order options and more quick view templates
I think many of us regularly work with calendar-style reports. It would be great to be able to customize the quick view with new templates and have options to sort the entries for each day of the calendar by different criteria. I think this is an interestingDeprecation Notice: OpenAI Assistants API will be shut down on August 26, 2026
I recieved this email from openAI what does it means for us that are using the integration and what should we do? Earlier this year, we shared our plan to deprecate the Assistants API once the Responses API reached feature parity. With the launch of Conversations,Shall we play a game?
Presenting the very first game created using ZOHO Creator: Tic-Tac-Toe (or noughts and crosses) I made this to challenge myself and employ some of the new features of ZOHO Creator. I must admit that the code is very literal and not too elegant. There are plans to improve on the machine AI and streamline the code over time. Currently the code makes extensive use of functions for the machine "AI" - there are 12 of these. The machine AI can be tricked, so to counteract that I made it exceedingly arrogantCRM notes
I want to be able to add notes to a task that do not necessarily get rolled up into an account or contact. For example, I tasks to work on a Court Order for John Doe divorce account. There might be lots of updates (in the form of notes) that employeesConfluence export to zoho learn
Hello Is there any known way to export Confluence spaces to zoho learn ?Zoho People API, Inactive users
Hi, I would like to export using the Zoho People API using Fetch Leave Records API V2 | Zoho People API. However it only pulls active user's leaves. I want all users, active and former employees records.Empty folders are now appearing in the sidebar...
...and the folder list is now auto-collapsed by default with no way to change. Neither of these recent updates are useful or user-friendly. ==================== Powered by Haiku https://www.haiku.co.uk ====================Client Script | Update - Client Script Support For Custom Buttons
Hello everyone! We are excited to announce one of the most requested features - Client Script support for Custom Buttons. This enhancement lets you run custom logic on button actions, giving you greater flexibility and control over your user interactions.Zoho CRM for Everyone's NextGen UI Gets an Upgrade
Hello Everyone We've made improvements to Zoho CRM for Everyone's Nextgen UI. These changes are the result of valuable feedback from you where we’ve focused on improving usability, providing wider screen space, and making navigation smoother so everythingCreate custom rollup summary fields in Zoho CRM
Hello everyone, In Zoho CRM, rollup summary fields have been essential tools for summarizing data across related records and enabling users to gain quick insights without having to jump across modules. Previously, only predefined summary functions wereMonthly Webinar - Getting Started with Zoho LandingPage
Are you building your first landing page and want a little guidance? Join our monthly Getting Started with Zoho LandingPage webinar and learn how landing pages fit into your marketing strategy, drive lead generation, and improve conversions. Here’s whatView all email threads directly from record's History and Interactions
Greetings all, We've introduced the ability to view complete email thread conversations directly from records' History and Interactions sections, along with email delivery status and sentiment insights on the Interactions page—which makes it easier forMarketing Tip #22: Check website and navigation for broken links
Do you inspect your online store frequently? If not, here's your reminder to do it now. Broken links frustrate customers and make your store feel unreliable. Whether it’s a missing product page, an outdated menu item, social media accounts, or a brokenCustom function return type
Hi, How do I create a custom deluge function in Zoho CRM that returns a string? e.g. Setup->Workflow->Custom Functions->Configure->Write own During create or edit of the function I don't see a way to change the default 'void' to anything else. Addingpush notification to Cliq when user is @mentioned in CRM notes
push notification to Cliq when user is @mentioned in CRM notes. Currently users that is @mentioned gets an email to be notified. User/s that is @mentioned should get a Cliq notification.How to make entries for restaurant sales in Zoho Books?
Hello, I'm new to Zoho Books. I need to understand how to record our restaurant sales in Zoho Books. We can't raise invoices for each bill from the daily sales report generated by our POS (duplicated effort). We need a means of entering cumulative salesIntegrate with WooCommerce using Wordpress Plugin
We’re thrilled to announce a powerful update to the Zoho Marketing Automation WordPress plugin with WooCommerce integration! This enhancement enables new possibilities for businesses running online stores using WooCommerce, empowering them to merge seamlessHow do I sync multiple Google calendars?
I'm brand new to Zoho and I figured out how to sync my business Google calendar but I would also like to sync my personal Google calendar. How can I do this so that, at the very least, when I have personal engagements like doctor's appointments, I canDomain already exists
Hi, I tried to add my domain creativecolumnist.com but its showing as Domain already exist. Please release if it has already been associated with Zoho, I am the real owner of that domain.Select forwarding
For Zoho mail online on PC in web browser: I had forwarding enabled in section "Mail accounts / Forwards", and I also have some filters that send emails from some unwanted senders to Archive. But it doesn't work as intended, it forwards everything (obviouslysystem not picking my default custom service report template
Can you tell me why when we create a service report always pick the (standard old) template? Even when I have a custom service report selected as Default.Restrict Appointment Booking to Approved Clients
Dear Zoho Bookings Support Team, We'd like to propose a feature enhancement for managing appointments within Zoho Bookings. This feature would ensure only pre-approved clients can schedule meetings. Desired Functionality: We propose the introduction ofAutomate Credit Card Surcharge
Is there a way to create an automation that will add a 3.0% credit card surcharge to a subscription whenever a customer pays via credit card?I have the item field and Quantity field in the sub form , on the submit of the form if the quantity is grater than inventory means show alert on submit validation only for item type goods ,
I have the item field and Quantity field in the sub form , on the submit of the form if the quantity is grater than inventory means show alert on submit validation . Stock Check Validation only for item type goods , not for item type service . For theDisappearance of all articles in the knowledge base
Hi there! It seems like all of our articles have disappeared from the knowledge base: However, the names still appear in the "sort articles" section:Logic for sending to a non-primary email address
Hi, I have a scenario where contacts are able to sign up for emails with 2 different email addresses (example: work, personal). I've mapped both to Campaigns from Zoho CRM, but when I go to target an email only the primary email addresses are pulling in. How can I update this to look at both of the email addresses - or specifically the secondary email address in Campaigns? Thanks, JennyNext Page