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
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 #197: Frequently Asked Questions on GraphQL APIs
🎊 Nearing 200th Kaizen Post – We want to hear from you! 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 #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.Celebrating 200 posts of Kaizen! Share your ideas for the milestone post
Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQsKaizen #193: Creating different fields in Zoho CRM through API
🎊 Nearing 200th Kaizen Post – We want to hear from you! 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.Client Script | Update - Introducing Commands in Client Script!
Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands
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
Marketing Automation List Entry Criteria is no longer an option
For a couple of years now we have used the "List Entry Criteria" option to filter our Journey recipient list. All of a suddent the option no longer exists for New Lists and I can only delete the option from existing lists but can no longer edit it. AnyoneGCLID arrives not in CRM with iframe integrated ZOHO Form
Hello amazing community, I enabled Adwords integration in ZOHO CRM. I have a ZOHO Form integrated in a wordpress. I tested iframe and Javascript. I enabled the "handover" GCLID in the ZOHO Form. When I add a GLID with http://www.example.com/?gclid=TeSter-123.How to overcome Zoho Deluge's time limit?
I have built a function according to the following scheme: pages = {1,2,3,4,5,6,7,8,9,10}; for each page in pages { entriesPerPage = zoho.crm.getRecords("Accounts",page,200); for each entry in entriesPerPage { … } } Unfortunately, we have too many entriesAdd Webhook Response Module to Zoho Flow
Hi Zoho Flow Team, We’d like to request a Webhook Response capability for Zoho Flow that can return a dynamic, computed reply to the original webhook caller after / during the flow runs. What exists today Zoho Flow’s webhook trigger can send custom acknowledgementsBidirectional sync between Zoho Bookings and Zoho CRM - Part 1
Hey, community members! The default integration between Zoho CRM and Zoho Bookings is unidirectional, which means that any appointments booked, rescheduled, or deleted in Zoho Bookings will be reflected in Zoho CRM. However, any modifications made toIs it possible to edit placeholder text?
In the master slides I want to make sure my templates have more meaning for the users and want to replace the standard placeholder text with something more instructional. Instead of "Click to edit Mast subtitle styles" I want to have "Click to enter reportingDelay function execute
I've got a workflow which uses a webhook to send information to Flow, which in return updates a record in Creator. Problem is, by the time this has executed, the rest of my script has run and can't find the (yet to be) updated info in the record. Is thereHow to allow download of a file AFTER information is collected?
I can't find this anywhere. Can someone help with what seems to be a pretty basic web function today? - File is stored in Workdrive - Prospect goes to a URL where the file is located - System requests prospect to enter "Name" and "Email" - An email isAdd Baseline methods to API
There are no API methods for creating or querying baselines, Use case: Customer is notified of the current project start date according to plan via another product/integration. We would like to auto create a baseline (Automated via API) at the pointBulk Fill In & Edit PO/Bill/SO/Invoice
Hello, I am adding stock in bulk on a PO, the system is automatically populating the Rate (price) and Tax from the item data. Problem is that the bill rate is different from the rate on the item data, so I have to manually erase each and enter the price.Fixed Assets beg balance
Hello, I trust you are well I'm a new zoho books user and I find it difficult to plug in the fixed assets balance and here's what I have done: 1- I imported the fixed assets data into the fixed assets module as per the instructions 2- the import processSyncing with Google calendar, Tasks and Events
Is it possible to sync Zoho CRM calendar, task and events with Google Calendar's tasks and events. With the increasing adoption by many major tool suppliers to sync seamlessly with Google's offerings (for instance I use the excellent Any.do task planningCRM Deluge how can link attach file with workdrive file.
Hi, We have create file at workdrive and would like to link to attachment at crm module by deluge. Right now can only upload it to attachment but can not link the file from workdrive. Thank youFeature announcement: AI-powered document generator in Zoho Sign
Hi there! We recently announced manual document creation by offering an editor within Zoho Sign. Today, we are excited to announce AI-powered document generation to help you draft agreements, purchase orders, and other important business documents inPermanently deleted files
Is there a way to get back permanently deleted files from your account if they were accidentally deleted and no longer recoverable from the recycling bin? I know I am probably screwed but I just figured I would ask.Shared Mailbox in iOS app
Hi, On the desktop I am using a Shared mailbox for our company's general mailbox that somebody else should be able to view. In the iOS app however I can't find it? Old sources on the internet says this isn't possible but that can't be right? SomebodyTip #41- Simplify Compliance and Efficiency with Zoho Assist’s Data Cleanup Feature- 'Insider Insights'
Managing device data efficiently is just as important as securing remote access. With Zoho Assist’s Data Cleanup feature, admins can easily remove outdated or unnecessary device records, keeping the console organized and secure. This action is carriedRevenue Management: #6 Revenue Recognition in Professional Services Industry
If you run a consulting firm, agency, or any service-based business, you have a situation where you have signed the contract, maybe even sent the invoice, and have received some initial payments. So, can you consider this as revenue? What if the projectZoho fsm scheduled maintenance dispatch
Hi, I'm reaching out regarding an issue I'm encountering with the Scheduled Maintenance feature in Zoho FSM. I’m trying to configure it so that it automatically dispatches all maintenance jobs scheduled within the next 150 days, starting from today. However,Template modifiactions
Hello, I am struggling with the templates in ZOHO Books. Especially with the placement of some items, like company address, ship to, bill to etc. For example: One item I like from template X (placement of ship to and bill to next to each other in thezoho.inventory.getRecords returns no records
I running a custom function (Deluge) in Zoho Flow with a connection to Zoho Inventory. To debug the problem, I created the test function below. It returns "Number of contacts fetched: 0". This confirms that there's no issue with the org ID or connectionZoho Campaigns Event timestamps do not propagate to Zoho CRM
We have integrated Zoho CRM and Zoho Campaigns. But when looking at Contact records, the Campaign event data is missing the actual timestamps: especially when a particular email was sent. They're not in the Campaigns related list, and the cannot be foundFeature announcement - Simplifying document creation with Zoho Sign
Hi there, We are pleased to announce the release of our document creation feature, enabling you to create, edit, and finalize documents like agreements, purchase orders, and contracts without relying on external tools or applications. <br> ThisIntegrating File Attachments in Zoho Flow Email Notifications
Hi, I would like to be able to send an email once an entry is made in a form, and in this email, I would like to attach a file that has been added to the form using the ImageUpload (or FileUpload) widget. So, I started by creating a flow that will triggerZoho Mail SMTP IP addresses
We are using Zoho Mail and needs to whitelist IP for some redirections from your service to another e-mails. You can provide IP address list for Zohomail SMTP servers?Zoho project purchases
Hi Folks, I think having a purchase module in projects will help in putting together a project p and L. Project wise purchases and expenses. Do let me know your thoughts.Create Tasklist with Tasklist Template using API v3
In the old API, we could mention the parameter 'task_template_id' when creating a tasklist via API to apply a tasklist template: https://www.zoho.com/projects/help/rest-api/tasklists-api.html#create-tasklist In API v3 there does not seem to be a way toHow can I restore all the deleted Time entries of a Task in Zoho Projects
How can I restore all the deleted Time entries of a Task in Zoho Projects? Query: In Zoho Projects, I cloned a task and deleted the time entries from the cloned task. However, this also deleted the time entries from the original task. How can I restoreIs there a way to make an account inactive in ZoHo Desk
We have a few Clients "Accounts" that we no longer do business with. It would be beneficial for them to not show up in lists. However, we want to go back and view tickets, time, etc.How to set the value of the Phone field importing contacts in Zoho Desk
Hi everyone, i'm new in Zoho Desk, we're setting up the environment and i'm importing contacts from another CRM using a file CSV and i'm getting a problem with phone numbers (italian): the leading zero is cut away, also if the value is inside double quotes.Set Custom Icon for Custom Modules in new Zoho CRM UI
Deprecation 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,How to center a field inside a section?
I’ve been trying to center a field inside a section in Zoho Canvas. When I align it visually, it looks centered in the editor, but after clicking Save, the field appears misaligned on the actual canvas. I also tried setting the field to full width, butKaizen #192 - Implementing Custom Token Persistence in Python SDK
Welcome back to another week of Kaizen! Last week, we discussed how to implement Login with Zoho using OAuth 2.0 and saw how to bring it to life in a real-world application with the Zoho CRM Python SDK. We also discussed how Zylker Academy built a customShowing the map along with mileage expense
When you use the GPS to track mileage, it shows you the map of the actual path travelled. It would be very useful and practical to save that map with the mileage expense, so that when the report is created, it provides a map of each mileage expense associatedEnable Validation Rule for Multi-Select Picklist Field
Zoho, Please allow validation rules for multi-select fields.File Upload field not showing in workflow
Hi, I have added a field on Zoho CRM. I want to use it in a workflow where that particular field is updated based on another field, however it is not showing up in the field list to select it in the workflow. Why is this please?CRM Custom function updating a module record shows the Super Admin user as the record modifier
Dear Zoho CRM Team, Is there any way to update this so that when a custom function has updated a record the Super Admin user doesn't become the modifier? This happens on the record as a modifier and shows up in the audit logs. It would be more usefulBest practice importing items and matching assemblies
Hi, I was wondering what would be the best practice to import items and composite items (assemblies) From my backup, what should I import first? The items or the composite items? I am on Zoho one, using inventory and books. Kind regards, SabineBest way to fetch employee names from Zoho People into Zoho Creator Inventory Stock Form field Employee Name Lookup
Hi Team, I have a requirement in my Zoho Creator application (Inventory Stock Adjustment) where I need to fetch employee names from Zoho People and use them as a lookup in a form. Currently, I am considering using an integration field to fetch this dataNext Page