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!













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

    • Kaizen #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

    • Recent Topics

    • How to export project tasks, including the comments

      Hi, how can I export the project tasks, whereby I can also see the comments associated to a specific task? The use-case is that often we use comments to discuss or update a task related ideas. I would like to export the tasks, where we can also see the

    • How to Install Zoho Workdrive Desktop Sync for Ubuntu?

      Hi. I am newbie to Linux / Ubuntu. I downloaded a tar.gz file from Workdrive for installing the Workdrive Desktop Sync tool. Can someone give me step by step guide on how to install this on Ubuntu? I am using Ubuntu 19.04. Regards Senthil

    • Introducing Version-3 APIs - Explore New APIs & Enhancements

      Happy to announce the release of Version 3 (V3) APIs with an easy to use interface, new APIs, and more examples to help you understand and access the APIs better. V3 APIs can be accessed through our new link, where you can explore our complete documentation,

    • Does Zoho Sheet Supports https://n8n.io ?

      Does Zoho Sheet Supports https://n8n.io ? If not, can we take this as an idea and deploy in future please? Thanks

    • Bigin Android app update: User management

      Hello everyone! In the most recent Bigin Android app update, we have brought in support for the 'Users and Controls' section. You can now manage the users in your organization within the mobile app. There are three tabs in the 'Users and Controls' section:

    • Share records with your customers and let them track their statuses in real time.

      Greetings, I hope everyone is doing well! We're excited to introduce the external sharing feature for pipeline records. This new enhancement enables you to share pipeline records with your customers via a shareable link and thereby track the status of

    • Live webinar: Discover Zoho Show: A complete walkthrough

      Hello everyone, We’re excited to invite you to our upcoming live webinar, Discover Zoho Show: A Complete Walkthrough. Whether you’re just getting started with Show or eager to explore advanced capabilities, this session will show you useful tips and features

    • Deal Stage component/widget/whatever it is... event

      Deal Stages I am trying to access the event and value of this component. I can do it by changing the Stage field but users can also change a Deal Stage via this component and I need to be able to capture both values. Clicking on 'Verbal' for instance,

    • Create advanced slideshows with hybrid reports using Zoho Projects Plus

      Are your quarterly meetings coming up? It’s time to pull up metrics, generate reports, and juggle between slides yet again. While this may be easier for smaller projects, large organizations that run multiple projects may experience the pressure when

    • Add an option to disable ZIA suggestions

      Currently, ZIA in Zoho Inventory automatically provides suggestions, such as sending order confirmation emails. However, there is no way to disable this feature. In our case, orders are automatically created by customers, and we’ve built a custom workflow

    • Email Integration - Zoho CRM - OAuth and IMAP

      Hello, We are attempting to integrate our Microsoft 365 email with Zoho CRM. We are using the documentation at Email Configuration for IMAP and POP3 (zoho.com) We use Microsoft 365 and per their recommendations (and requirements) for secure email we have

    • Formula field with IF statement based on picklist field and string output to copy/paste in multi-line field via function

      Hello there, I am working on a formula field based on a 3-item picklist field (i.e. *empty value*, 'Progress payment', 'Letter of credit'). Depending on the picked item, the formula field shall give a specific multi-line string (say 'XXX' in case of 'Progress

    • CRM x WorkDrive: File storage for new CRM signups is now powered by WorkDrive

      Availability Editions: All DCs: All Release plan: Released for new signups in all DCs. It will be enabled for existing users in a phased manner in the upcoming months. Help documentation: Documents in Zoho CRM Manage folders in Documents tab Manage files

    • Zoho CRMの流入元について

      Zoho CRMとZoho formsを連携し、 formsで作成したフォームをサイトに埋め込み運用中です。 UTMパラメータの取得をformsを行い、Zoho CRMの見込み客タブにカスタム項目で反映される状況になっています。 広告に関してはUTMパラメータで取得できているため問題ないのですが、オーガニック流入でフォーム送信の場合も計測したいです。メールやGoogle、Yahoo、directなどの流入元のチャネルが反映されるようにしたいのですが、どのように設定したら良いでしょうか。 また、

    • Error While Sign in on Zoho Work Drive

      Dear Team, I hope this email finds you well. I have recently created a Zoho account and started using it. But while I am trying to log in to Zoho work drive it won't log me in its crashing every time I try it. I have tried it on android app, phone browser

    • Choosing a portal option and the "Unified customer portal"?

      I am trialling Zoho to replace various existing systems, one of which is a customer portal. Our portal allows clients to add and edit bookings, complete forms, manage their subscriptions and edit some CRM info. I am trying to understand how I might best

    • Elevate your CX delivery using CommandCenter 2.0: Simplified builder; seamless orchestration

      Most businesses want to create memorable customer experiences—but they often find it hard to keep them smooth, especially as they grow. To achieve a state of flow across their processes, teams often stitch together a series of automations using Workflow

    • Unified Directory : How to Access ?

      I signed in to Zoho One this morning and was met with the pop up about the upgraded directory (yay!) I watched the video and pressed "Get Started" ... and it took me back to the standard interface. How do I actually access the new portal/directory ?

    • Translation support expanded for Modules, Subforms and Related Lists

      Hello Everyone!   The translation feature enables organizations to translate certain values in their CRM interface into different languages. Previously, the only values that could be translated were picklist values and field names. However, we have extended

    • Unified task view

      Possible to enable the unified task view in Trident, that is currently available in Mail?

    • Bigin, more powerful than ever on iOS 26, iPadOS 26, macOS Tahoe, and watchOS 26.

      Hot on the heels of Apple’s latest OS updates, we’ve rolled out several enhancements and features designed to help you get the most from your Apple devices. Enjoy a refined user experience with smoother navigation and a more content-focused Liquid Glass

    • Importing data into Assets

      So we have a module in Zoho CRM called customers equipments. It links to customers modules, accounts (if needed) and products. I made a sample export and created extra fields in zoho fsm assets module. The import fails. Could not find a matching parent

    • Allow instruction field in Job Sheets

      Hello, I would like to know if it is possible to have an instruction field (multi line text) in a job sheet or if there is a workaround to be able to do it. Currently we are pretty limited in terms of fields in job sheets which makes it a bit of a struggle

    • Streamlining Work Order Automation with Zoho Projects, Writer & WorkDrive

      Hello Community, Here is the first post in 'Integration & Automation' Series. Use Case :: Create, Merge, Sign & Store Documents in Zoho WorkDrive. Scenario :: You have a standard Work Order template created in Zoho Writer. When a task status is chosen

    • The dimensions of multilingual power

      Hola, saludos de Zoho Desk. Bonjour, salutations de Zoho Desk. Hallo, Grüße von Zoho Desk. Ciao, saluti da Zoho Desk. Olá, saudações da Zoho Desk. வணக்கம், Zoho Desk இலிருந்து வாழ்த்துகள். 你好，来自 Zoho Desk 的问候。 مرحباً، تحيات من Zoho Desk. नमस्ते, Zoho

    • Multi-line address lines

      How can I enter and migrate the following 123 state street Suite 2 Into a contact address. For Salesforce imports, a CR between the information works. The ZOHO migration tool just ignores it. Plus, I can't seem to even enter it on the standard entry screen.

    • Accessing Zoho Forms

      Hi all, We're having trouble giving me access to our company's Zoho Forms account. I can log in to a Forms account that I can see was set up a year ago, but can't see any shared forms. I can log into Zoho CRM and see our company information there without

    • Archiving Contacts

      How do I archive a list of contacts, or individual contacts?

    • Cost of good field

      Is there a way we can have cost of good sold as a field added to the back end of the invoicing procedure and available in reports?

    • How to add image to items list in Invoice or Estimate?

      Hello! I have just started using Zoho Invoice to create estimates and, possibly to switch from our current CRM/ERP Vendor to Zoho. I have a small company that is installing CCTV systems and Alarm systems. My question is, can I add images of my "items" to item list in Zoho Invoice and Estimates and their description? I would like to show my clients the image of items in our estimates so they can decide if they like these items. And I tell you, often they choose more expensive products just because

    • Issue with the Permission to Zoho Form

      I am getting an error by signing in to zoho form as it is stated that i don't have permission to access this is admin account

    • CRM templates

      Hello everyone, In my company we use Zoho campaigns where we set up all newsletters and we use Zoho CRM for transactional emails. I have created some templates in Zoho campaigns but from my understanding i cannot use those in Zoho CRM, right?

    • Meet Canvas' Grid component: Your easiest way to build responsive record templates

      Visual design can be exciting—until you're knee-deep in the details. Whether it's aligning text boxes to prevent overlaps, fixing negative space, or simply making sure the right data stands out, just ironing out inconsistencies takes a lot of moving parts.

    • Addin Support in Zoho Sheet

      Is there any addin support available in zoho sheet as like google marketplace to enhance productivity by connecting with other apps, providing AI data analysis, streamlining business processes, and more?

    • Where to integrate Price Book and Product List Price

      Hello, We sync zoho crm all modules with all data to zoho analytics. In zoho crm, we have "Price Books" and "Products" modules, where each product is assigned to a few price books with different list prices. From zoho crm, I am able to export a dataset

    • Pending Sales Order Reports

      Pending sale order report is available for any single customer, Individual report is available after 3-4 clicks but consolidated list is needed to know the status each item. please help me.

    • Zoho 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?

    • Migrate Your Notes from OneNote to Zoho Notebook Today

      Greetings Notebook Users, We’re excited to introduce a powerful new feature that lets you migrate your notes from Microsoft OneNote to Zoho Notebook—making your transition faster and more seamless than ever. ✨ What’s New One-click migration: Easily import

    • Zoho Campaigns - Why do contacts have owners?

      When searching for contacts in Zoho Campaigns I am sometimes caught out when I don't select the filter option "Inactive users". So it appears that I have some contacts missing, until I realise that I need to select that option. Campaigns Support have

    • One Contact with Multiple Accounts with Portal enabled

      I have a contact that manages different accounts, so he needs to see the invoices of all the companies he manage in Portal but I found it not possible.. any idea? I tried to set different customers with the same email contact with the portal enabled and

    • Next Page