Kaizen #31 - Subforms #API

Kaizen #31 - Subforms #API

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

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

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


To know more about Subforms, refer to
Building Subforms.

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

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

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

1. Insert Subform Records

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

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

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

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

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

Sample Input

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

Response:


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


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

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

2. Update Subform Records

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

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

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



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

Sample Input

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

Response:



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

Possible Errors

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

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

3. Get a Subform

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

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

Response:



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

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

The response is as below.



4. Delete Subform Records

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


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

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

Cheers!













    Access your files securely from anywhere



                          Zoho Developer Community




                                                  • Desk Community Learning Series


                                                  • Digest


                                                  • Functions


                                                  • Meetups


                                                  • Kbase


                                                  • Resources


                                                  • Glossary


                                                  • Desk Marketplace


                                                  • MVP Corner


                                                  • Word of the Day


                                                  • Ask the Experts





                                                            Manage your brands on social media



                                                                  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

                                                                                      • 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 Writer

                                                                                              Get Started. Write Away!

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

                                                                                                Zoho CRM コンテンツ










                                                                                                  Nederlandse Hulpbronnen


                                                                                                      ご検討中の方




                                                                                                            • Recent Topics

                                                                                                            • Introducing Assemblies and Kits in Zoho Inventory

                                                                                                              Hello customers, We’re excited to share a major revamp to Zoho Inventory that brings both clarity and flexibility to your inventory management experience! Presenting Assemblies and Kits We’re thrilled to introduce Assemblies and Kits, which replaces the
                                                                                                            • Can I add Conditional merge tags on my Templates?

                                                                                                              Hi I was wondering if I can use Conditional Mail Merge tags inside my Email templates/Quotes etc within the CRM? In spanish and in our business we use gender and academic degree salutations , ie: Dr., Dra., Sr., Srta., so the beginning of an email / letter
                                                                                                            • What is the Use Case for Business Messaging when Live Chat already exists?

                                                                                                              Hi I'm excited about the new announcement for Business Messaging in Zoho Desk. However I'm unclear the use case for Business Messaging when Live Chat already exists? Is Business Messaging essentially a new version of Live Chat but built for use in the
                                                                                                            • Edit Pinned Comments in Zoho Desk

                                                                                                              It's great that private comments can now be pinned to the top of the ticket but what would be extremely helpful would be to allow for the pinned comment to be edited vs. having to find the comment in the ticket to edit it.
                                                                                                            • Introducing the 'Send as Email' option on the Zoho Desk iOS mobile app

                                                                                                              Hello everyone! In the latest version(v2.10.2) of the Zoho Desk iOS app, we have brought in support for the 'Send as Email' option while creating a ticket. This feature enables you to reach out to the customers by sending outbound emails. The emails are
                                                                                                            • Document data extraction and import into CRM.

                                                                                                              I've been trying to solve this for a while and I can't come up with a workable solution: In our business, we utilize many subcontractors around the world (without Zoho user accounts) to produce reports and client sites which they then submit back to us
                                                                                                            • Modular cannot Edit in portals

                                                                                                              I have a custom module in CRM. If I create in either CRM or portals, I can edit it in the CRM but I can't edit in the portal. Even if it is created in the portal it wont edit. Anyone know why? I've created a new module and it works fine but this one
                                                                                                            • Zoho CRM and Books Integration

                                                                                                              Evening, I have started the integration with FSM from CRM and having difficulties with the mapping. In CRM we use "Unit Price" as our cost price and mark this up on a subform to create a "Sell Price" this markup can be different on each quote depending
                                                                                                            • Plug Sample #13: Display CRM Products as Dynamic Carousels in Your Chatbot

                                                                                                              Hi everyone! We’re back with another simple yet powerful plug to level up your chatbot experience. With the SalesIQ-CRM integration, you already have the ability to create leads, contacts, and deals directly within your CRM from SalesIQ, and view complete
                                                                                                            • Como puedo mover un prospecto "Cliente" de modulo

                                                                                                              Tengo un modulo llamado Seguimiento de Ventaa y otro llamado Cierre de Venta. Que cuando se marca como venta efectiva o venta no efectiva, pase a Cierre de Venta, Esto sin duplicarlo "Que esten en ambos modulos" ,Como esta en una base de datos "Excel"
                                                                                                            • Zoho Books not working/loading

                                                                                                              Hi! I haven't been able to access/load Zoho Books for the past hours. I get a time out (and it is not due to my internet connection). Could you please check this asap? Thank you!
                                                                                                            • Introducing ICR in Zoho CRM: Transform your printed text into digital data

                                                                                                              From writing on papyrus in the ancient times to creating a humble record in your CRM, the world may have evolved with how it used to record data, but data entry as such has not been simplified. It is still a repetitive and arduous chore on which businesses
                                                                                                            • Max limit reached on Web Tabs for Zoho Projects

                                                                                                              Hello, ByWater manages between 50-60 projects at a time, and we have been heavily utilizing the Web Tab feature. However, we just hit our maximum limit reached for web tabs. The main thing we use Web Tabs for is sharing a Google document with our partners
                                                                                                            • Creating a whatsapp channel in instant messaging in zoho desk - error Oops, something went wrong. Please try again later.

                                                                                                              Creating a whatsapp channel in instant messaging in zoho desk - error Oops, something went wrong. Please try again later.
                                                                                                            • Article Update Event

                                                                                                              I'm trying to configure a webhook to fire when an article is updated or added. These are listed as available events in the documentation. However, in the webhook creation/editing screen, articles are not listed as a module when setting the event: Am I
                                                                                                            • Kaizen #187 - Building a Timer and Worklog Widget (Part 1)

                                                                                                              Howdy Tech Wizards! Welcome back to a fresh week of Kaizen! This time, we are diving into a two-part series where you will learn how to build a Timer and Worklog Widget for Zoho CRM. This widget helps track active work time and log multitasking sessions
                                                                                                            • Task Permissions

                                                                                                              Is there anyway to have some tasks restricted to view just by the owner or creator?
                                                                                                            • Zoho CRM Forecast - Exclude certain Deals

                                                                                                              We have our forecast and we use it for team forecast/targets/attainment. It works great for that. However, occassionally we have to offer Deals that are non-revenue generating, but are tracked in our CRM. They still have revenue tied to them, but our
                                                                                                            • Kaizen #154 - Dynamically Update Picklist Values in Zoho CRM Workflows

                                                                                                              Hello all! Welcome back to another interesting Kaizen post. Today, we will discuss how to add automatically or remove values from a picklist field using Deluge within a workflow. This post serves as a solution for the forum post. Use case The sales team
                                                                                                            • What is VoC "Unique count", counting?

                                                                                                              Using the "Response based sentiment analysis" dashboard, here is our VoC "Overall Count by Sentiment" VoC uses Zoho Survey and email...and we have almost certainly touched (via email) more than 401 Contacts since January 1, 2025.
                                                                                                            • Filter a report for a specific bank and a specific transaction type (interest income)

                                                                                                              I am trying to run a report - any report - on a specific bank account for the interest income. I do not see it as an option. I can see the Bank Account under Account in the Filters, and I can see the Interest Income under Account in the Filters But I
                                                                                                            • Ability to select Vendor Credits when creating Vendor Payments

                                                                                                              When making vendor payments there should be the option to select open vendor credits, this way the payment shows what bills and credits are being used for the payment Right now the vendor credits must be applied to the bills prior creating a payment,
                                                                                                            • Sorting Tasks by Start Date

                                                                                                              I like using the Tasks tool so far but have one little problem that would help me tremendously. This is my favorite aspect of using Outlook for task management.  When I create a task - I give the Start and Due Date. Some tasks are a little longer and may take a few days, while others only take a few minutes. For example, if a task takes 5 hours, and I want to spend 1 hour per day on it.  Because of this - knowing the start date is much more important than the due date.  The ability to sort by Start
                                                                                                            • Single payment link for multiple invoices or total due for a customer on Whatsapp.

                                                                                                              I want to send a single payment link for multiple invoices or total due for a customer on Whatsapp. Currently zoho books do not have this option . While sending WhatsApp template, payment link is created for particular invoice. I want to send WhatsApp
                                                                                                            • Whatsapp Customer Statement and Outstanding

                                                                                                              Customers are asking to whatsapp statement or outstanding report or invoices regularly. Is there a way we can integrate it in Zoho Books. We already have Whatsapp Business API from Interakt and regular Whatsapp API from MessageAutoSender. How can we use
                                                                                                            • Owner's Draw

                                                                                                              Example: I have a charge account at ABC Company. During the month I charge one $50 item for my business. I also pick up a $20 item for personal use. At the end of the month, I receive a statement with a balance due of $70 and I want to PAY THE ENTIRE
                                                                                                            • Show both Vendor and Customers in contact statement

                                                                                                              Dear Sir, some companies like us working with companies as Vendor and Customers too !!! it mean we send invoice and also receive bill from them , so we need our all amount in one place , but in contact statement , is separate it as Vendor and Customer, 
                                                                                                            • Adding google reviews

                                                                                                              HI , is it possible to add my google reviews to my zoho website ? Thank you 
                                                                                                            • Display an image in Zoho reports report

                                                                                                              I have a table report in which i'd like to display an image made up of data from another column, something like: <img src="records.photo"> However, when i do that, nothing happens.  How do i pull it off?  
                                                                                                            • Currency fields and decimal places in CRM email templates

                                                                                                              Hi, How do I get more than the standard 2 decimal places showing in a Currency field, on an email template? In the Layout for my Currency field, it is set to 6 decimal places. I want to show up to 6 places in the email template (unrounded). See attached
                                                                                                            • GST Returns India

                                                                                                              1. Have been requesting that the documents issued section should be filled automatically. If other accounting software can do it ZOHO Books can. NOT ROCKET SCIENCE !! 2. There is an Issue with the Debit Notes not showing up in GSTR 1 ???  Sorry but this is unacceptable !! as a GST Suvidha provider and an accounting software developer both these errors are unforgivable. P.S: Another GST issue is that the GSTR 2 reconciliation has to be closed monthly to do the next month, Maybe ZOHO developers should
                                                                                                            • Getting error "invalid warehouse_id" when trying to update any transaction in Zoho books

                                                                                                              I got a message from Zoho saying that the Warehouse and Branch has been merged into one category "Locations" Once I migrated to this setup I was no longer able to edit any invoice / create creadit notes - got an error saying "invalid warehouse_id" I never
                                                                                                            • E-Way Bill Generation and Custom Button Requirement in Stock Transfer Module in ZOHO Books India

                                                                                                              We would like to provide further clarification and highlight a few operational challenges we're currently facing : we are handling stock transfers between branches/warehouses within the same state under the same GSTIN. As per government rules, E-Way Bill
                                                                                                            • Subform data to Sheets

                                                                                                              I have been trying to setup a Zoho Flow automation to bring any Subform input to a Zoho Sheets but it seems impossible to post the subform entries to a Zoho Sheet. Is there any way to do it via Zoho Sheet API? https://www.zoho.com/sheet/help/api/v2/#CONTENT-Insert-row-with-JSON-data
                                                                                                            • Voiding of Invoice

                                                                                                              What's the implication in GSTR 1 and GSTR 3B when an invoice is voided?
                                                                                                            • Search WorkDrive File Contents from Creator

                                                                                                              Good afternoon, I am building out a Creator app where I want to allow users to input search terms from Creator that will return the appropriate files that contain those keywords from their Creator search. Is this possible?
                                                                                                            • execute workflow when a package is create

                                                                                                              hji, there is a wey to make a workflow when a package is sended o created ?
                                                                                                            • Adding string / text fields to modules

                                                                                                              I'm working on a custom leads module with a layout for call center agents.  I need to add text fields that are for display purposes only to prompt call center agents.  I haven't found any way to add a field in Zoho CRM that doesn't accept input, ie. is
                                                                                                            • Looking to Hire: Zoho Creator Developer for Vendor Dashboard Portal

                                                                                                              We are a Florida-based licensed liquor distributor using Zoho Books, Inventory, CRM, and Analytics. Many of our vendors are also our customers. We’re looking to build a centralized, secure Vendor Dashboard Portal in Zoho Creator that gives access to real-time
                                                                                                            • Automate Zoho Meeting Creation via Blueprint (Leads & Accounts)

                                                                                                              I need help automating Zoho Meeting creation during a blueprint transition in both the Leads and Accounts modules. Requirements: Triggered via blueprint Read meeting start time (DateTime field) and internal participants from CRM Create Zoho Meeting via
                                                                                                            • Next Page