Kaizen #31 - Subforms #API

Kaizen #31 - Subforms #API

Hello everyone!
Welcome back to another post in the Kaizen series.
In this post, we will discuss the Subform APIs.

What is a Subform?
A subform is a secondary form or a table that enables you to include multiple line items into a primary form. Every line item is a subform record.
Your CRM data are often inter-dependent. Often, you may have the necessity to associate multiple items to a single record. In the technical lingo, we call these "line items".
Consider we have a Students module to store student records. Apart from the data like name, age, date of birth, email ID, courses opted for etc, we may want to have information such as the languages a student knows and the proficiency level in that language. So, Languages can be a subform in the Students module, and Language and Proficiency can be the two fields in that subform.
Therefore, every row in this subform that holds the language and the proficiency is a subform record or a line item.

Here is how the subform looks in a record in the Students module.


To know more about Subforms, refer to Building Subforms.

Note
The Subform API is available only in the Enterprise and Ultimate editions of Zoho CRM.

Let us see how to insert, update, and delete these subform records through the APIs.

Subform APIs
  1. Insert Subform Records
  2. Update Subform Records
  3. Get a Subform
  4. Delete Subform Records

1. Insert Subform Records

You must use the Insert Subform Records API to insert records to a subform while inserting a record to a module.

Details Required: 
      a. API Name of the subform.
      b. API name of the subform fields.

a. API name of the subform
  1. Make a Get Modules API call. The response displays the details of all the available modules.
  2. Search for the module in which you have created the subform. In our case, it is Students.
  3. Look for the value of the key "generated_type" as "subform". 
  4. The value of the key "api_name" gives the API name of the subform. In our case, it is Languages.

b. API name of the subform fields
  1. Make a Get Fields Metadata API call to the subform module (crm/v2/settings/fields?module=Languages).
  2. Search for the field label. The value of the "api_name" key for the fields in the subform are the API names. Here, they are Proficiency and Language.
  3. Note down the "json_type" that represents the type of value the subform fields accept. Here, they are pick lists that accept string values.

To insert subform records:
Request URL: {{api-domain}}/crm/v2/Students
Request method: POST

Sample Input

{
    "data": [
        {
            "Name":"Allan John",
            "Languages1": [
                {
                    "Proficiency": "Native",
                    "Language": "English"
                },
                {
                    "Proficiency": "Professional",
                    "Language": "French"
                }
            ]
        }
    ]
}

Response:


Note
  • A module can have a maximum of two subforms for all editions except Ultimate. The Ultimate edition can have a maximum of five subforms.
  • Every module can have a maximum of 200 subform records with each subform having a maximum of 100 records.
  • A maximum of five aggregate custom fields are available for a subform.
Possible Errors
The "details" key in the response gives you an idea of where the error occurred. This key contains the API name of the field that has incorrect input and other necessary information in other keys.


HTTP Status and Error Code
"details" key
Reason for error
Handling
400 - INVALID_DATA
"details" : {
"api_name":"sub_form_api_name",
"expected_data_type":"jsonarray"
}
Invalid input for subform.

Construct proper subform data and send it in the request body.
400 - INVALID_DATA
"details" : {
"expected_data_type":"data_type",
 "api_name" : "name_of_field",
 "index" : "subform_array_index",
"parent_api_name":"subform_api_name"
}
You have input Invalid data type for the field.
Use parent_api_name, index, and api_name to identify the invalid field and use expected_data_type to construct a proper value.
400 - INVALID_DATA
"details" : {
 "api_name" : "subform_api_name",
 "info" : "Maximum of 100 records allowed"
}
A subform can only have a maximum of 100 records.
Do not associate further records to the mentioned subform.

2. Update Subform Records

Now that we have created a subform, every subform row is a record with a unique ID. 
Use the Update Subform Records API to update the subform record(s).

Let us now update the subform entries we just added to the Languages subform in the Students module.
The changes we are making are:
      a. Adding a subform entry for the Language "Spanish" with Proficiency as "Professional".
      b. Updating the Proficiency of the Language "French" to "Native".

Details required:
Record IDs of the subform records that you want to update. Make a Get Subform Data API call to the Student record you want to update the subform in.



The request to update the subform is
Request URL: {{api-domain}}/crm/v2/Students/3652397000002125005
Request method: PUT

Sample Input

{
    "data": [
        {
            "Languages": [
                {
                    "Proficiency": "Professional", //new subfrom record
                    "Language": "Spanish"
                },
                {
                    "id":"3652397000002125020",  //ID of the subform record that you want to update
                    "Proficiency": "Native",
                    "Language": "French"
                },
                {
                   "id":"3652397000002125019" //ID of the subform record that does not need any change
                }
            ]
        }
    ]
}

Response:



Note
  • You must specify the record IDs of the subform records you want to update and also the ones you do not want to update.
  • If you do not specify their IDs, the system deletes those records from the subform.

Possible Errors

HTTP Status and Error Code
"details" key
Reason for error
Handling
400 - INVALID_DATA
"details" : {
"api_name":"sub_form_api_name",
"expected_data_type":"jsonarray"
}
Invalid input for subform.
Construct proper subform data and send it in the request body.
400 - INVALID_DATA
"details" : {
"expected_data_type":"data_type",
 "api_name" : "name_of_field",
 "index" : "subform_array_index",
"parent_api_name":"subform_api_name"
}

You have input invalid data type for the field.
Use parent_api_name, index, and api_name to identify the invalid field and use expected_data_type to construct a proper value.
202- INVALID_DATA
Message: the id given seems to be invalid
1. Either the record ID or the subform record ID is invalid, (or)
2. User does not have the permission to the mentioned record.
1. Check the record ID sent in the API request URL or in the request body (or)
2. Check the subform record ID sent in the request body.

3. Get a Subform

You can use the Get Subform Data API to fetch the details of the subform of a record.
In the response, the key Parent_Id gives the name and ID of the record that the subform record is associated to.

Request URL: {{api-domain}}/crm/v2/Languages
Request method: GET

Response:



You can also get the subform details when you fetch a record from the module the subform is created in.

Request URL: {{api-domain}}/crm/v2/Students/3652397000002125005
Request method: GET

The response is as below.



4. Delete Subform Records

Simply make an Update Subform Records API call to the record whose subform record you want to delete.
Specify only the IDs of the subform records that you want to retain. The system deletes the other subform records whose IDs you have not specified.


We hope you found this post useful. Stay tuned for more!

Write to us at support@zohocrm.com if you have any questions, or let us know in the comment section.

Cheers!













    Access your files securely from anywhere

        All-in-one knowledge management and training platform for your employees and customers.






                              Zoho Developer Community



                                  Bootcamp
                                  Community
                                  Pricing
                                  Webinars
                                  What's New
                                  Integrations
                                  Contact Support
                                  Contact Sales
                                    Zoho Survey Resources
                                      Features
                                      Survey Templates
                                      Integrations
                                      Community
                                      iOS Mobile Surveys
                                      Pricing
                                      Android Mobile Surveys
                                      Insurvey Blogs
                                      Insight Blogs
                                      Tips & Tricks





                                                  Latest Feature Updates

                                                    • Desk Community Learning Series


                                                    • Digest


                                                    • Functions


                                                    • Meetups


                                                    • Kbase


                                                    • Resources


                                                    • Glossary


                                                    • Desk Marketplace


                                                    • MVP Corner


                                                    • Word of the Day


                                                    • Ask the Experts




                                                        Zoho SalesIQ Resources

                                                              • Sticky Posts

                                                              • Kaizen #198: Using Client Script for Custom Validation in Blueprint

                                                                Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

                                                              • Kaizen #226: Using ZRC in Client Script

                                                                Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In this

                                                              • Kaizen #222 - Client Script Support for Notes Related List

                                                                Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore how

                                                              • Kaizen #217 - Actions APIs : Tasks

                                                                Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.

                                                              • Kaizen #216 - Actions APIs : Email Notifications

                                                                Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are


                                                              Manage your brands on social media
                                                              Access Zoho Social

                                                                Zoho Pagesense Resources


                                                                    Zoho TeamInbox Resources

                                                                      Zoho DataPrep Resources


                                                                        Zoho CRM Plus Resources

                                                                          Zoho Books Resources


                                                                            Zoho Subscriptions Resources

                                                                              Zoho Projects Resources


                                                                                Zoho Sprints Resources


                                                                                  Qntrl Resources


                                                                                    Zoho Creator Resources



                                                                                        Zoho CRM Resources

                                                                                        • CRM Community Learning Series

                                                                                          CRM Community Learning Series


                                                                                        • Kaizen

                                                                                          Kaizen

                                                                                        • Functions

                                                                                          Functions

                                                                                        • Meetups

                                                                                          Meetups

                                                                                        • Kbase

                                                                                          Kbase

                                                                                        • Resources

                                                                                          Resources

                                                                                        • Digest

                                                                                          Digest

                                                                                        • CRM Marketplace

                                                                                          CRM Marketplace

                                                                                        • MVP Corner

                                                                                          MVP Corner







                                                                                            Design. Discuss. Deliver.

                                                                                            Create visually engaging stories with Zoho Show.

                                                                                            Get Started Now


                                                                                              Zoho Show Resources

                                                                                                Zoho Writer

                                                                                                Get Started. Write Away!

                                                                                                Writer is a powerful online word processor, designed for collaborative work.

                                                                                                  Zoho CRM コンテンツ




                                                                                                    Nederlandse Hulpbronnen


                                                                                                        ご検討中の方




                                                                                                                • Recent Topics

                                                                                                                • Deluge Error Code 1002 - "Resource does not exist."

                                                                                                                  I am using the following script in a Custom Button on a Sales Return. Basically, the function takes the information in the sales return (plus the arguments that are entered by the user when the button is pushed) and creates a return shipping label via

                                                                                                                • Adding multiple Attendee email addresses when adding a Zoho Calendar event in Zoho Flow

                                                                                                                  I am trying to integrate Notion and Zoho Calendar via Zoho Flow. However, the Attendee email address supported by Zoho Calendar - Create event only supports one email address, so I am having difficulty implementing automation to automatically register

                                                                                                                • Graceful Handling of Exceeded Option Limits

                                                                                                                  Hi Zoho SalesIQ team. I would like to submit a feature request to deal with a bug in salesIQ Current Behavior (Bug): When a dynamic list passed to the Single Select Option Card contains more than 20 options, the Zobot stops responding (freezes/hangs)

                                                                                                                • System default SLA descriptions can't be modified

                                                                                                                  The system default SLAs have identical descriptions for all SLA levels, but their settings differ. However, I am facing an issue where I cannot modify these descriptions and save the changes. The content of the description box can be edited but the changes

                                                                                                                • Adding non-Indian billing address for my Zoho subscription

                                                                                                                  Hey Need help with adding a non-Indian billing address for my Zoho subscription, trying to edit the address to my Singapore registered company. Won't let me change the country. Would appreciate the help. Regards, Rishabh

                                                                                                                • How to create one ZohoCRM organisation out of a multi-organization?

                                                                                                                  Hi, we have a multi-org including two different Zoho CRM organizations for two companies using respectively EUR and USD as default currency. I was wondering if there is any easy way to merge the two organizations into just one, so that users may access

                                                                                                                • Gray screen while signing documents

                                                                                                                  We are all getting a "gray" screen when trying to sign documents in Zoho sign. Anyone else having issues?

                                                                                                                • Projects custom colors replaced by default orange

                                                                                                                  Since yesterday, projects uploaded to Zoho, to which I had assigned a custom color, have lost the customization and reverted to the default color (orange). Has anyone else had the same problem? If so, how did you resolve it?

                                                                                                                • Interview booked through Invite but no Notifications

                                                                                                                  We have a workflow that was developed through a developer/partner that was tested and worked. Today, we pushed a candidate through the process and invited them to an in-office interview. They were sent the booking link (as usual and as tested before successfully)

                                                                                                                • Automatiser la gestion des SLA dans Zoho Desk avec Zoho Contracts

                                                                                                                  Les équipes du service client s’efforcent d’assurer un support rapide, régulier et fiable pour garantir la satisfaction de chaque client. Les accords de niveau de service (SLA) permettent de clarifier les engagements en définissant les termes et conditions

                                                                                                                • iOS App doesn't refresh for Document Creation

                                                                                                                  Hello Zoho team, I have created a workflow to be used on a mobile iOS device which starts in Zoho Creater and ends with a murge and store function that then opens the newly created document within the Zoho Writer app. This process is working great however

                                                                                                                • Uploading a signed template from Sign to Creator

                                                                                                                  Good day, Please help me on how to load a signed document back into Creator after the process has been completed in Sign. Below is the code that I am trying, pdfFile = response.toFile("SignedDocument_4901354000000372029.pdf"); info pdfFile; // Attach

                                                                                                                • Zoho DataPrep and File Pattern configuration

                                                                                                                  I'm using Zoho data prep to ingest data from One Drive into Zoho Analytics... The pipeline is super simple but I can't any way to get all the files that I need. Basically I need to bring all the files with a certain pattern and for that I'm using a regex

                                                                                                                • Assistance needed: Activation of a domain

                                                                                                                  Hello Zoho Support, I purchased the .com domain "primesolva.com" via Zoho 6 days ago. The domain is still pending, and I cannot access the DNS panel to add the TXT verification for domain ownership. Please confirm the registration status and help me activate

                                                                                                                • Operation not permitted

                                                                                                                  I am trying to add an email address to the list of user but I am getting error Operation not permitted

                                                                                                                • Request to Permanently Delete Email User (info@mehbobgulf.com ) from Old Organization

                                                                                                                  Please permanently delete the user email info@mehbobgulf.com It is still associated with my old Zoho organization. I cannot delete it because it shows ‘You cannot delete email. Zoho host’. I need to use this email in a new Zoho account.”

                                                                                                                • Client host [89.36.170.5] blocked using Spamhaus

                                                                                                                  Hello please make make actions for delist ..... "Client host [89.36.170.5] blocked using Spamhaus"

                                                                                                                • Suggestion: Option to Re-run a migration

                                                                                                                  As I'm going through a migration process, I like the IMAP migration tool, but it would be better if there were an option to re-run the same migration as configured. There's not even an option to copy/edit one that's already there. Just run if it hasn't

                                                                                                                • Issue with "Add Your Mobile Number"

                                                                                                                  Hello, I am trying to sign up for email service for a domain name, and I cannot finish the authentication. When I enter my mobile number, I receive the message "We’re unable to send OTP to this mobile number. Please contact support-as@zohocorp.com". I

                                                                                                                • zoho mail non vérifié

                                                                                                                  Bonjour, Il y'a un jour que j'ai acheté un domaine et toute les tentatives pour l'associé a mon compte shopify son vaine. j'ai essayé TXT sans suite après, j'ai essayer avec CNAME sans suite. j'aurais besoin de votre assistance pour associé mon mail.

                                                                                                                • Unable to send message;Reason:553 Relaying disallowed. Invalid Domain

                                                                                                                  i have facing the issue "Unable to send message;Reason:553 Relaying disallowed. Invalid Domain" if i verify domain evertthing i did but still face the same error.

                                                                                                                • Override Auto Number field?

                                                                                                                  We are preparing to migrate from Salesforce. In Salesforce, we auto-generate a unique number on our Opportunities (Potentials). If the Opportunity results in a contract, we use that unique number as the Contract number. There are some situations where

                                                                                                                • Using a third party service provider want to move directly with Zoho

                                                                                                                  Hi good day I’m currently using Zoho but I’m using a third party service provider I want to move directly with you guys I’m using Zoho email and invoices and my domain please let me know if it’s possible to move away from the third party provider my email

                                                                                                                • Request for Assistance Regarding Email Sending Issue (554 5.1.8 - Email Outgoing Blocked)

                                                                                                                  Dear Zoho Support Team, I hope this message finds you well. I am writing to request assistance with an issue we are currently facing regarding our Zoho Mail account. Our email account, admin@tuyensinhcanuoc.com, is encountering the following error when

                                                                                                                • Zoho Mail API returns empty inbox (0 messages) but webmail shows 37 unread emails

                                                                                                                  Hello, I'm experiencing a discrepancy between Zoho Webmail and the Mail API (EU region). **Setup:** - Account: EU datacenter (mail.zoho.eu) - API: Self Client OAuth2 via api-console.zoho.eu - Scopes: ZohoMail.messages.READ, ZohoMail.messages.UPDATE, ZohoMail.folders.READ,

                                                                                                                • ShipStation and Zoho Inventory

                                                                                                                  Hello, I am looking to sync zoho inventory with shipstation ZOHO INVENTORY           SHIP STATION Sales Order  ==>  create ORDERS INVOICE  <==    Shipments What exactly does BETA mean on the Shipstation connector?  This is required for me to sign-on in the next month. Thanks in advance for your efforts

                                                                                                                • E

                                                                                                                  We are trying to add our Zoho Form embed in our Elementor Page Builder. After adding Zoho Forms widget in elementor page builder it’s displaying in backend page builder but it’s giving 403 error while trying to save, as it’s not reflecting in front end.

                                                                                                                • custom module import.

                                                                                                                  Is there a way to import data into a custom module? Thanks Rudy

                                                                                                                • HEIC File Type Viewer

                                                                                                                  Hi, It would be nice to be able to click on the images in the All Entries/Reports Tables which are HEIC the same as JPG, PNG, etc. so they open in a viewer from Zoho or the Attachment Service, today HEIC requires you to download each image and open it

                                                                                                                • Building Toppings #4 - Setting up and using connections in Bigin toppings

                                                                                                                  When building a topping to extend Bigin's functionality and connect it with third-party applications, creating and handling connections is an important step. Connections provide a secure way for your topping to authenticate and communicate with other

                                                                                                                • Need code format to specify default values

                                                                                                                  Can someone please direct me to the code syntax or the proper translation per the instructions circled below. These instructions don't seem correct.

                                                                                                                • AI Interview Insights: Turn Recorded Interviews into Quick Transcripts & Summaries

                                                                                                                  Evaluating interviews shouldn’t require replaying long recordings or taking manual notes. With AI Interview Insights, you can now review complete transcripts and AI-generated summaries of your One-way (Recorded) interviews right inside Zoho Recruit. This

                                                                                                                • Record payment: Payment Mode vs. Deposit To and how to "connect" them!?

                                                                                                                  How do we set up that when we choose:  "Payment Mode"= Cash, then "Deposit to" is automatically set to Petty Cash, and if we choose  "Payment Mode"= Check, then "Deposit to" is automatically set to Undeposited Checks, and if we choose  "Payment Mode"=

                                                                                                                • Grouping Undeposited Funds to Move to other accounts

                                                                                                                  In the bank option it would be nice to check what transactions in undeposited funds I want to move to other accounts. Then while checking this it can accumulate totals and created whats essentially a deposit slip. Once the transaction is moved it should

                                                                                                                • Facing email delivery issues? Verify your domain's DNS records

                                                                                                                  Have you ever wondered why your legitimate emails are landing in the recipient’s spam folder? Or been surprised to see emails sent from your registered domain getting rejected by recipient email servers? Why does this happen? In most cases, this happens

                                                                                                                • Order of Departments in Help Desk

                                                                                                                  In the end user portal, , the departments are sorted by the date of creation of the department (or perhaps their id). Is there a way to choose the display order of the departments or at least to be able to sort them alphabetically?

                                                                                                                • COGS - Account showing negetive

                                                                                                                  I have multiple COGS account and in these all there is one account is negetive so suggest why it is showing negetive value.?

                                                                                                                • Create CRM Deal from Books Quote and Auto Update Deal Stage

                                                                                                                  I want to set up an automation where, whenever a Quote is created in Zoho Books, a Deal is automatically created in Zoho CRM with the Quote amount, customer details, and some custom fields from Zoho Books. Additionally, when the Sales Order is converted

                                                                                                                • Google Photos

                                                                                                                  I am hoping that my question already has a fix. I current have Google synced accounts that I want to get away from. One in particular on is Google photos. Is there any software, or 3rd parties that I can join to back my photos up straight to specifically designated file in the ZOHO cloud that's tied to Docs? Please advise... Mike 

                                                                                                                • Zoho Books Items Categorisation/Grouping/Folder

                                                                                                                  Is there a way to do items categorisation? a folder structure? Product Type A - Option 1/2/3 Product Type B - Option 1/2/3 Current problem : I have more than 50 items on the list, its hard for team to navigate.

                                                                                                                • Next Page