Kaizen #31 - Subforms #API
Hello everyone!
Welcome back to another post in the Kaizen series.
In this post, we will discuss the Subform APIs.
What is a Subform?
A subform is a secondary form or a table that enables you to include multiple line items into a primary form. Every line item is a subform record.
Your CRM data are often inter-dependent. Often, you may have the necessity to associate multiple items to a single record. In the technical lingo, we call these "line items".
Consider we have a Students module to store student records. Apart from the data like name, age, date of birth, email ID, courses opted for etc, we may want to have information such as the languages a student knows and the proficiency level in that language. So, Languages can be a subform in the Students module, and Language and Proficiency can be the two fields in that subform.
Therefore, every row in this subform that holds the language and the proficiency is a subform record or a line item.
Here is how the subform looks in a record in the Students module.
Note
The Subform API is available only in the Enterprise and Ultimate editions of Zoho CRM.
Let us see how to insert, update, and delete these subform records through the APIs.
Subform APIs
- Insert Subform Records
- Update Subform Records
- Get a Subform
- Delete Subform Records
1. Insert Subform Records
You must use the Insert Subform Records API to insert records to a subform while inserting a record to a module.
Details Required:
a. API Name of the subform.
b. API name of the subform fields.
a. API name of the subform
- Make a Get Modules API call. The response displays the details of all the available modules.
- Search for the module in which you have created the subform. In our case, it is Students.
- Look for the value of the key "generated_type" as "subform".
- The value of the key "api_name" gives the API name of the subform. In our case, it is Languages.
b. API name of the subform fields
- Make a Get Fields Metadata API call to the subform module (crm/v2/settings/fields?module=Languages).
- Search for the field label. The value of the "api_name" key for the fields in the subform are the API names. Here, they are Proficiency and Language.
- Note down the "json_type" that represents the type of value the subform fields accept. Here, they are pick lists that accept string values.
To insert subform records:
Request URL: {{api-domain}}/crm/v2/Students
Request method: POST
Sample Input
{ "data": [ { "Name":"Allan John", "Languages1": [ { "Proficiency": "Native", "Language": "English" }, { "Proficiency": "Professional", "Language": "French" } ] } ] } |
Response:
Note
- A module can have a maximum of two subforms for all editions except Ultimate. The Ultimate edition can have a maximum of five subforms.
- Every module can have a maximum of 200 subform records with each subform having a maximum of 100 records.
- A maximum of five aggregate custom fields are available for a subform.
Possible Errors
The "details" key in the response gives you an idea of where the error occurred. This key contains the API name of the field that has incorrect input and other necessary information in other keys.
HTTP Status and Error Code | "details" key | Reason for error | Handling |
400 - INVALID_DATA | "details" : { "api_name":"sub_form_api_name", "expected_data_type":"jsonarray" } | Invalid input for subform. | Construct proper subform data and send it in the request body. |
400 - INVALID_DATA | "details" : { "expected_data_type":"data_type", "api_name" : "name_of_field", "index" : "subform_array_index", "parent_api_name":"subform_api_name" } | You have input Invalid data type for the field. | Use parent_api_name, index, and api_name to identify the invalid field and use expected_data_type to construct a proper value. |
400 - INVALID_DATA | "details" : { "api_name" : "subform_api_name", "info" : "Maximum of 100 records allowed" } | A subform can only have a maximum of 100 records. | Do not associate further records to the mentioned subform. |
2. Update Subform Records
Now that we have created a subform, every subform row is a record with a unique ID.
Use the Update Subform Records API to update the subform record(s).
Let us now update the subform entries we just added to the Languages subform in the Students module.
The changes we are making are:
a. Adding a subform entry for the Language "Spanish" with Proficiency as "Professional".
b. Updating the Proficiency of the Language "French" to "Native".
Details required:
Record IDs of the subform records that you want to update. Make a Get Subform Data API call to the Student record you want to update the subform in.
The request to update the subform is
Request URL: {{api-domain}}/crm/v2/Students/3652397000002125005
Request method: PUT
Sample Input
{ "data": [ { "Languages": [ { "Proficiency": "Professional", //new subfrom record "Language": "Spanish" }, { "id":"3652397000002125020", //ID of the subform record that you want to update "Proficiency": "Native", "Language": "French" }, { "id":"3652397000002125019" //ID of the subform record that does not need any change } ] } ] } |
Response:
Note
- You must specify the record IDs of the subform records you want to update and also the ones you do not want to update.
- If you do not specify their IDs, the system deletes those records from the subform.
Possible Errors
HTTP Status and Error Code | "details" key | Reason for error | Handling |
400 - INVALID_DATA | "details" : { "api_name":"sub_form_api_name", "expected_data_type":"jsonarray" } | Invalid input for subform. | Construct proper subform data and send it in the request body. |
400 - INVALID_DATA | "details" : { "expected_data_type":"data_type", "api_name" : "name_of_field", "index" : "subform_array_index", "parent_api_name":"subform_api_name" } | You have input invalid data type for the field. | Use parent_api_name, index, and api_name to identify the invalid field and use expected_data_type to construct a proper value. |
202- INVALID_DATA | Message: the id given seems to be invalid | 1. Either the record ID or the subform record ID is invalid, (or) 2. User does not have the permission to the mentioned record. | 1. Check the record ID sent in the API request URL or in the request body (or) 2. Check the subform record ID sent in the request body. |
3. Get a Subform
You can use the Get Subform Data API to fetch the details of the subform of a record.
In the response, the key Parent_Id gives the name and ID of the record that the subform record is associated to.
Request URL: {{api-domain}}/crm/v2/Languages
Request method: GET
Response:
You can also get the subform details when you fetch a record from the module the subform is created in.
Request URL: {{api-domain}}/crm/v2/Students/3652397000002125005
Request method: GET
The response is as below.
4. Delete Subform Records
Simply make an Update Subform Records API call to the record whose subform record you want to delete.
Specify only the IDs of the subform records that you want to retain. The system deletes the other subform records whose IDs you have not specified.
We hope you found this post useful. Stay tuned for more!
Write to us at support@zohocrm.com if you have any questions, or let us know in the comment section.
Cheers!
Access your files securely from anywhere
New to Zoho Recruit?
Zoho Developer Community
New to Zoho LandingPage?
Zoho LandingPage Resources
New to Zoho Survey?
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Bigin?
Topic Participants
Shylaja S
DataWarehouse
Sticky Posts
Kaizen #197: Frequently Asked Questions on GraphQL APIs
🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Kaizen #198: Using Client Script for Custom Validation in Blueprint
Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Celebrating 200 posts of Kaizen! Share your ideas for the milestone post
Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQsKaizen #193: Creating different fields in Zoho CRM through API
🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Client Script | Update - Introducing Commands in Client Script!
Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands
New to Zoho TeamInbox?
Zoho TeamInbox Resources
Zoho CRM Plus Resources
Zoho Books Resources
Zoho Subscriptions Resources
Zoho Projects Resources
Zoho Sprints Resources
Qntrl Resources
Zoho Creator Resources
Zoho CRM Resources
Design. Discuss. Deliver.
Zoho Show Resources
Get Started. Write Away!
Writer is a powerful online word processor, designed for collaborative work.
Zoho CRM コンテンツ
-
オンラインヘルプ
-
Webセミナー
-
機能活用動画
-
よくある質問
-
Ebook
-
-
Zoho Campaigns
- Zoho サービスのWebセミナー
その他のサービス コンテンツ
Nederlandse Hulpbronnen
ご検討中の方
Recent Topics
Migrating a Zoho Forms form into Zoho Creator
Hi, How can I migrate my Zoho Forms form into Zoho Creator? Thanks. Truly, EmadIs there any way to recall an email sent using Zoho CRM?
If an email is sent using Zoho Mail, there is a recall option/functionality that is available to the sender. Is there any way to recall an email if it was sent using Zoho CRM? I can't seem to find that option. Any help would be appreciated.Quick Create needs Client Script support
As per the title. We need client scripts to apply at a Quick Create level. We enforce logic on the form to ensure data quality, automate field values, etc. However, all this is lost when a user attempts a "Quick Create". It is disappointing because, fromis it possible to add more than one Whatsapp Phone Number to be integrated to Zoho CRM?
so I have successfully added one Whatsapp number like this from this User Interface it seems I can't add a new Whatsapp Number. I need to add a new Whatsapp Number so I can control the lead assignment if a chat sent to Whatsapp Phone Number 1 then assignProblem with reports due to "Connected" items change - Yes this IS a problem
Now that the change has been made to use "connected" items I can no longer run the reporting I need in CRM. I should be able to start with Deals as the parent, connect down to the Account (Account_Name) on the deal as the child, then to any child itemsZoho sheet desktop version
Hi Zoho team Where can I access desktop version of zoho sheets? It is important as web version is slow and requires one to be online all the time to do even basic work. If it is available, please guide me to the same.Introducing notifications in the vendor portal
Imagine this: You're a recruiter working with multiple vendors on a high-volume hiring project. You’ve just updated a job description after a last-minute change from the hiring manager. One of your vendors, however, is still working off the older versionCRM limit reached: only 2 subforms can be created
we recently stumbled upon a limit of 2 subforms per module. while we found a workaround on this occasion, only 2 subforms can be quite limiting in an enterprise setting. @Ishwarya SG I've read about imminent increase of other components (e.LESS_THAN_MIN_OCCURANCE - code 2945
Hi I'm trying to post a customer record to creator API and getting this error message. So cryptic. Can someone please help? Thanks VarunHow to update "Lead Status" to more than 100 records
Hello Zoho CRM, How do I update "Lead Status" to more than 100 records at once? To give you a background, these leads were uploaded or Imported at once but the lead status record was incorrectly chosen. So since there was a way to quickly add records in the system no matter how many they are, we are also wondering if there is a quicker way to update these records to the correct "Lead Status". I hope our concern makes sense and that there will be a fix for it. All the best, JonathanAnalytics for notes created
Is there a way I can see how many notes were created per day? Via reporting or analytics?Add Custom Reports To Dashboard or Home Tab
Hi there, I think it would be great to be able to add our custom reports to the Home Tab or Dashboards. Thanks! ChadCannot update Recurring_Activity on Tasks – RRULE not accepted
Hello, I am trying to update Tasks in Zoho CRM to make them recurring yearly, but I cannot find the correct recurrence pattern or way to update the Recurring_Activity field via API or Deluge. I have tried: Sending a string like "RRULE:FREQ=YEARLY;INTERVAL=1"Add image to report...
Greetings, I send a weekly color coded report via Creator email. I would like to add the legend somewhere in the report. Header, footer where ever. I have the legend saved on Google Drive and can access it via shared link. Sure someone has wanted to addMore controls for User Fields in CRM
Dear All, We are here with a minor but crucial enhancement to the user fields—now set accessibility permissions to the records for user field. User field allows you to extend co-ownership of records to your peers. You can collaborate with them for certainCalls to accounts rather than leads or contacts?
So..... We have a dilemma and I'm hoping someone has encountered this before and figured out a fix. We have just migrated to Zoho. It's great.....expect for how "Calls" are handled.... We are B2B. We do not use the leads module. A "Lead/Prospect" forImage Upload Field | Zoho Canvas
I'm working on making a custom view for one of our team's modules. It's an image upload field (Placement Photo) that would allow our sales reps to upload a picture of the house their working on. However, I don't see that field as a opinion when buildingPower of Automation :: Automated 'Delayed & Closed' Status Update Based on Due Date
Hello Everyone, A custom function is a software code that can be used to automate a process and this allows you to automate a notification, call a webhook, or perform logic immediately after a workflow rule is triggered. This feature helps to automateLead Blueprint transition in custom list view
Hi, Is It possible to insert the Blueprint transition label in a custom Canvas list view? I am using Lead module. I see the status, but it would be great if our users could execute the Blueprint right from the list view without having to enter the detailedRange names in Zoho Sheet are BROKEN!
Hi - you've pushed an update that has broken range names. A previously working spreadsheet now returns errors because the range names are not updating the values correctly. I've shared a video with the support desk to illustrate the problem. This spreadsheetHas anyone integrated SMS well for Zoho Desk?
Our company does property management and needs to be able to handle inbound sms messages which create a ticket for Zoho Desk. We then need to be able to reply back from Zoho desk which sends the user an sms message. This seems like a fairly common thingpopulate email address and name in zoho desk?
Is it possible to populate the email address and name in the zoho desk widget? We only use it in the context of an authenticated user, so we already know the user's name and email. Thanks,Are there default/pre-built dashboards in Zoho Desk?
Hi, I am looking for some pre-built dashboard templates in Zoho Desk, similar to what we can find in CRM/Projects, etc Thank youEnable Locations for Expense
Hi, please enable Locations (ex Branches) for Zoho Expense so that there is consistency between this app and Zoho Books. Thanks in advance.Adding branded signature to tickets reply
Hi, i am unable to figure out how to add signatures with logo to tickets reply. please advice .Zoho Marketing Automation 2.0 - Landing Page function not working
Dear Zoho Team, I am working on implementing Zoho Marketing Automation 2.0, and am now looking into the section "Lead Generation". If I open the "Landing Pages" section, I immediately get an Error code: Error: internal error occurred. Can you help meZoho Mail Android app update: Manage folders
Hello everyone! In the latest version(v2.9) of the Zoho Mail Android app update, we have brought in support for an option to manage folders. You can now create, edit, and delete folders from within the mobile app. You can also manage folders for the POPHow to share ticket numbers across different ticket types
I'm running an event and have three different ticket types. Add on Event + Main Event - Early bird Main Event only - Early bird Add on Event only - Early bird And Standard class - shown but not available until early bird finishes Add on Event + Main EventHow to keep track of bags, cans, drums of inventory?
We buy and sell products that are packaged in bags 🛍️, cans🥫, drums🛢️, etc. with batch numbers. When we get a shipment of one of the products, how do we track we received (say) 10 cans each of 5L of a product and maybe we received 10 cans of anotherAdding Social Media Buttons to Basic Campaigns
Hi, I'm quote new to using Zoho Campaigns and I can't work out how to add Social Media Buttons into my basic campaign? In MailChimp there's a button that brings the icons into your campaign for you. I've tried adding the social media icons as 'buttons' in Zoho but it's not looking great. Can anyone help? Thanks!Hide Inactive Social Sign-In Providers from Login Screen
Hello Zoho Team, We hope you are doing well. Currently, Zoho One allows admins to configure security policies and enable or disable Social Sign-In options for third-party providers such as Apple, Google, Microsoft, LinkedIn, Yahoo, Twitter, Facebook,[Free Webinar] AI Agents in Zoho Creator - Creator Tech Connect
Hello Everyone! We welcome you all to the upcoming free webinar on the Creator Tech Connect Series. The Creator Tech Connect series is a free monthly webinar that runs for around 45 minutes. It comprises technical sessions in which we delve deep intoDownload All Attached Files
It would be extremely useful to have "download-all" functionality for downloading files attached to a task, subtask, comment, forum post or hosted in the "Documents" section etc. We've instructed our users to zip multiple files prior to uploading, but of course they forget all the time. Having to download lots of files one-at-a-time off a comment or task wastes a lot of time.Ship via Carrier Not Working Since Commerce Update
Since the recent update to the Commerce platform, I can no longer use the ship via carrier function. It will take me to the address screen and let me verify them but when I go to save and move tot he next screen it will not do anything. This is happeningautomations: Can I execute a step on a specific date?
I have created a form in Zoho forms, and created a contacts list. I have also begun setting up an automation with the intention of sending the form to the contact list on a specific date every month (via email) for the entire year (essentially sendingZoho Expense - The ability to add detail to a Trip during booking
As an admin, I would like the ability to add more detail to the approved Trips. At present a requestor can add flights, accommodation details and suggest their preferences. It would be great if the exact details of the trip could be added either by theAdding Folders in Android App
Is it possible to create a new email folder within the Zoho Mail Android app? Or can this only be done from the desktop version of Zoho Mail? Cheers!Schedule Exports for Regular Project Updates
Tracking project data often means exporting data at regular intervals. Instead of manually exporting data every time, users can schedule exports for Phases, Tasks, and Tasks in Zoho Projects. These exports can be set to run once, daily, weekly, or monthlyQuestion about custom fields using Pivot Tables.
I have created a pivot table showing annual revenue of a client and how much payment that client is paying my company. Is there a way using pivot table to add an additional field that subtracts those to fields / shows me a percentage of that difference?Request for Light/Dark Mode
Would love the ability to switch between Light and Dark mode similar to Zoho CRM. https://help.zoho.com/portal/en/community/topic/introducing-dark-mode-light-mode-a-new-look-for-your-crmNext Page