Kaizen #124 - Manipulating Subform using Zoho CRM APIs

Kaizen #124 - Manipulating Subform using Zoho CRM APIs

Hello everyone!

Welcome back to another post in our Kaizen series. 
In this post, we will discuss how to manipulate the Subform data using Zoho CRM APIs.

Subforms

A Subform is a data section embedded in the primary form to collect details related to the parent record. It helps in maintaining multiple records under a single parent record. 

Using subform, you can create a parent-child relationship between modules, where the parent module represents the primary data and the child module contains the related data. 

Data Model Representation
The above diagram shows the data model representation when you create a subform in a module.
Consider adding a subform field named Project Details in the Leads module (parent module). Zoho CRM will automatically create a separate module for the subform field with the specified subform field name - Project Details. Each record within the subform module can have multiple fields, in addition to the system-defined Parent_Id lookup field, establishing a connection between the parent (Leads module) and child (subform module) modules. Through this linking process, one can easily identify which subform record corresponds to which specific lead record.

Use Case

Consider Zylker Consulting organization using Zoho CRM to maintain their leads and their projects. Zylker uses the Project Details subform in the Leads module to collect project-specific information collected from their Leads.
The Project Details subform includes fields such as Project Title,Type, Budget, and Status, in addition to the Parent_Id lookup field.
Now, the Zylker's sales team needs to retrieve all the details of the projects from the Leads module for further project analysis, expected budgets, and status. Let's see how to manipulate these data in CRM using Zoho CRM APIs.

The APIs used in this post

API
Methods
Subforms API
GET, POST, UPDATE
Records API
POST, UPDATE, DELETE
Search API
GET
COQL API
POST
Bulk Read API
POST, GET

How to retrieve subform records using the Zoho CRM APIs?

To retrieve subform records from the subform module, specify the subform module's API name to access their records or fields.

Step - 1
To know the API names of the subform fields in a module, make a GET - Fields Metadata API call. Among all the Leads' fields, subform field can be identified by the json key data_type with the value subform. Corresponding subform module can be found from the json associated_module. Below is the API call & response for such a subform field.

Request URL :
{api-domain}/crm/v6/settings/fields/{subform_field_id}?module=Leads

Request Method: GET

Sample Response:


Step - 2
Using the api_name of the subform module, make a GET Fields metadata API call to get the list of fields (along with their api_name) in the subform. One of the fields of the subform module will be Parent_Id with the data_type as lookup, pointing to the parent module (here it is Leads).

Request URL 
Request Method: GET
Sample Response:
Now you know how to get the API name of the subform and its corresponding fields.

Step - 3
Sample Request and Response to retrieve subform records
The below request will retrieve all the subform records in the Leads module. The linking of subform record to the Lead's module will be available in the Parent_Id field, which is highlighted. The id key inside the Parent_Id json object is the id of the Leads records.
 


How to add data to the subforms?

To add records to the subform, you need the API name of the subform and its corresponding field API names.
Request URL:
Request Method:  POST
Sample Input
{
    "data": [
        {
            "Last_Name": "Patricia",
            "Company": "Info Technology",
            "Email" : "patricia@mail.com",
            "Project_Details": //API name of the subform
     [ 
                {
                    "Project_Name": "Mobile App Development for Productivity",
                    "Project_Type": "Mobile App Development",
                    "Expected_Budget": 50000,
                    "Status": "Negotiation in Process"
                }, //API names of the subform fields
                {
                    "Project_Name": "Big Data Infrastructure Implementation",
                    "Project_Type": "Infrastructure Upgrade",
                    "Expected_Budget": 30000,
                    "Status": "Proposal Submitted"
                },
                {
                    "Project_Name": "Big Data Infrastructure Implementation",
                    "Project_Type": "Infrastructure Upgrade",
                    "Expected_Budget": 30000,
                    "Status": "Proposal Submitted"
                }
            ] 
        }
    ]
}

The above highlighted syntax is used for adding data to the subform records. 

Sample Response:

Kaizen #33 - Subforms API explains in detail how to Fetch, Update, and Delete the subform data with sample requests, inputs, and responses.

Retrieve Subform Data via Search API and COQL API

There may be situations where you need to fetch records based upon certain conditions.  

Criteria :
The sales team wants to retrieve the subform records whose budget is greater than or equal to $40000. In this case, we will use Zoho CRM's Search API and COQL API. Let's see how to achieve this. 

Search API

To retrieve the records that match your search criteria, retrieve subform data using its corresponding module API name.  Note that using Search API, you can fetch data quickly from a single module.

Request URL:

Request Method: GET
Sample Response :
The above response shows all records that meet the specified criteria.

How to retrieve subform records from a particular parent record?

To retrieve subforms records in a particular lead record that meet the above criteria, follow the below sample request.

Sample Request URL:

Sample Response:



Retrieving Subforms Data via COQL API

We know that the subform is maintained in a separate module. So, retrieve subform data by querying the subform module's API name and it's parent module via the Parent_Id lookup field. 

Request URL:
Request Method : POST

Sample Input:
{
 "select_query" : "select Expected_Budget from Project_Details where ((Expected_Budget >=40000) and (Parent_Id = 5725767000002105043))"
}

Sample Response:
Using a Parent_Id (lookup field pointing to Leads module) in the COQL criteria automatically adds a left join to the child module (Project_Details). With that join, criteria can be applied to the fields of the parent module also. Below example illustrates that we want to fetch the Expected_Budget field of the Project_Details module where the Expected_Budget is greater than or equal to 40000 for the corresponding Leads with Annual Revenue greater than 1000000. 

{
 "select_query" : "select Expected_Budget from Project_Details where ((Expected_Budget >=40000) and (Parent_Id.Annual_Revenue > 100000 ))"
}

From the SQL perspective, above COQL can be interpreted as

select pd.Expected_Budget from Project_Details as pd left join Leads as l on pd.Parent_Id=l.id where pd.Expected_Budget>=40000 and l.Annual_Revenue > 1000000

For more information on COQL API, refer to the Kaizen posts  COQL Part -1 and COQL Part - 2

Bulk Read API

Bulk Read API allows you to fetch a large set of data i.e., you can fetch a maximum of 200,000 records in a single API call. 
To export subform records in the Leads module in CSV file format, use the subform's API name.

Request URL:
Request Method: POST

Sample input to export subform records:
{
    "callback": {
        "method": "post"
    },
    "query": {
        "module": {
            "api_name": "Project_Details" //API name of the Subform module
        },
        "file_type": "csv"
    }
}


Export subform records that meet the specified criteria

To export subform records based on the given criteria above (similar to the criteria for Search and COQL APIs).

Sample Input:
{
        . . .
     "query": {
        "module": {
            "api_name": "Project_Details"
        },
        "fields": [
            "Project_Name",
            "Project_Type",
            "Expected_Budget",
            "Status"
        ],
        "criteria": {
            "field": {
                "api_name": "Expected_Budget"
            },
            "comparator": "greater_equal",
            "value": "40000" //Retrieving subform records with an expected budget greater than or equal to $40,000
        }
    }
}


Export subform records that meet the specified criteria for the particular parent record

To export the subform records of a particular parent record in the Leads module. Check the below sample request.

Sample Input:

{
       . . .
        "query": {
        "module": {
            "api_name": "Project_Details"
        },
        "fields": [
            "Project_Name",
            "Project_Type",
            "Expected_Budget",
            "Status"
        ],
        "criteria": {
            "group": [
                {
                    "field": {
                        "api_name": "Expected_Budget"
                    },
                    "comparator": "greater_than",
                    "value": "39999"
                },
                {
                    "field": {
                        "api_name": "Parent_Id"
                    },
                    "comparator": "equal",
                    "value": "5725767000002105043"
                }
            ],
            "group_operator": "AND"
        }
    }
}


As the API is an asynchronous API, the response will not be available instantly; the bulk read job is scheduled, and the status can be checked. Once the job is completed, it'll be notified in the callback URL. The records are available in a downloadable CSV file or ICS file (for events). You can export subform records in a module using the subform module API name. See Kaizen #12 Bulk Read API to know how to view the status of the scheduled job and download the file, along with more sample requests and responses.

Frequently Asked Questions

Q.  Is the API name of the subform case-sensitive? Also, how can I view the API name of a subform field in the web UI?
Yes, the API name of a subform is case-sensitive. To know the API name of a subform module (e.g. Project Details) Please go to Setup -> Developer Hub -> APIs -> CRM API -> API names -> Click on the parent module where the subform was created (e.g. Leads) and scroll down there you can view the subform field's API name.

Q. I changed the order of subform records and made a GET - Records API call. The system listed the records in the same order as displayed in the UI, rather than the order of their creation. Is this the system design? 
When you make a GET - Records API call for a module, it lists the subform records ordered in the UI. Note that you can re-order the subform records. So, when you retrieve those records via the API, they will be listed in the same order as they are arranged in the UI.

Q. Can we change a subform field's API name via API?
You can change the API name of the subform field only through the UI. Go to Setup -> Developer Hub -> APIs -> CRM API -> API names -> Click on the parent module where the subform was created (e.g. Leads) and go to the Field Label section. There you can view the subform field name and edit the API by clicking on the Edit option.

We trust that this post meets your needs and is helpful. Let us know your thoughts in the comment section or reach out to us at support@zohocrm.com

Stay tuned for more insights in our upcoming Kaizen posts!
------------------------------------------------------------------------------------------------------------------------------
Previous Kaizen Post : Kaizen #123 Data Synchronization from a third party application
-------------------------------------------------------------------------------------------------------------------------------



Cheers!

Additional Reading:

Kaizen Posts:





    • Recent Topics

    • Avalara Sales Tax integration - AVATAX

      Just wondering if anyone else is having troubles with this integration?  Seems as though Avalara changed their billing process, unbeknownst to Zoho, and now ALL transactions are counted by Avalara, not just transactions in a taxable jurisdiction.  This caused a huge price adjustment billed to us by Avalara within a month of us signing up.  And Avalara is not cheap to begin with! Avalara has been great in waiving that increase, but there seems to be no fix.  Zoho is aware of the problem, but slow

    • Invalid value passed for description

      Dear Sir, When I am entering the purchase bill , the following message showing "Invalid value passed for description" what should I do ? I am attaching screenshot. With Regards, Harish harish@cracku.in 7978841636

    • Zoho Creator - 2024 Release Projection 1

      Hello everyone! As we enter 2024, we'd like to extend our warmest wishes for success and prosperity. Your fantastic response to our Product Roadmap page last year has been incredibly motivating. Continuing on this path, we're excited to share a glimpse

    • Automation Assistance for Zoho Form Integration and Workflow

      Hi, We are currently using a Zoho Form to send out our Global Credit Application and would like to automate the process further. Specifically, we’d like the ABN number submitted through the form to automatically populate the GST/VAT Number field in Zoho

    • COQL does not return queryable value if the result set is empty

      See linked video for running code illustration of the problem: https://workdrive.zohoexternal.com/external/d49bb40033b43b288d56fdf843095b7c65b28391d3ec5d09c854f416d853003d Moderation update: We are appending the comment that was removed, to add context

    • Zoho CRMでの商談の管理のしかたについて初歩的な質問です。

      先月からZoho CRMを試験的に導入して運用しています。 商談の管理（運用？）の仕方について教えてください。 商談の数が増えてくると、ダッシュボードの「ステージ別進捗状況」にどんどん過去の商談が蓄積されてくると思うのですが、 現在動きのあるものを中心に確認したくなる気がします。 そのあたりについては、どのように運用が一般的なのでしょうか？ アドバイスいただけるととてもありがたいです。 よろしくお願いします。

    • Composite Items & Purchase Orders

      The Composite Item is great way to bundle different products and services into a single line and sell it as a single line item in Estimates, Sales Orders and Invoices. However, on the other side - i,e,. Purchasing - this item creates quite a bit of a

    • using custom function is it possible to update the created by field in Zoho Crm custom module

      using custom function is it possible to update the created by field in Zoho Crm custom module

    • Slow Sloww Slowwww Responses

      Good day, Has anyone been experiencing slow responses from support? Since Thursday I migrated my Whats app to Sales Iq and I had to synch with Social to get the otp they were sending. Apparently What's app can't be automatically added so I reached out

    • You have exceeded the maximum number of attempts for this action. Please retry doing the same in 30 minutes.

      When one of Zoho Books user tries to select a vendor, recording a new bill, these message appears: You have exceeded the maximum number of attempts for this action. Please retry doing the same in 30 minutes. Other user, at the same time, but different

    • Enable Conversation Context Retention for SalesIQ Answer Bots

      Hello Zoho SalesIQ Team, We hope you are doing well. We have noticed that SalesIQ bots currently fail to maintain conversation context in Hebrew. For example, when we follow up on a previous answer or ask for clarification in Hebrew, the bot either provides

    • Automatic Hebrew Small Talk Setup Without Duplicate Term Errors & Manual Configuration

      Dear Zoho SalesIQ Team, Greetings, We would like to request an enhancement to the Small Talk feature in Zoho SalesIQ, specifically for Hebrew language support. Current Challenge: When setting up Small Talk for Hebrew, we encounter multiple issues: Simple

    • Should I Add Leads in Bigin?

      ok, first off I'm new here. I just started using Bigin. I'm debating if it's appropriate to enter leads. by leads I mean a list of contacts that I have not yet reached out to...it's a cold calling list.  if I enter them I can track them (I understand

    • Zoho Books - Perform a validation check before an invoice is marked as sent or sent

      Allow the validation rules to apply to button actions. For example: an invoice could not be sent or marked as sent if it has an empty value in a custom field. (The field could remain blank while it is being worked on.)

    • Flow error "given url is wrong"

      when I setup a flow to update a task status, I get an error when it runs that says "given url is wrong."

    • Upgrade Zoho Desk Agent-Side Answer Bot to GenAI

      Hello Zoho Desk Team, We hope you're doing well. Following the recent announcements and rollout of the GenAI-based Answer Bot in Zoho SalesIQ (Nova '25), we’d like to formally request a similar upgrade for the Answer Bot used by agents inside Zoho Desk.

    • Bigin Android app update: Email filters enhancement, change owner for related records.

      Hello, everyone! In the most recent Bigin Android app update, we have introduced additional email filters and an option to change the owner of related records. Email filters: We have now brought in support for 'All Emails' and 'Added from Widgets' filter

    • How can I get all conversations and comments of a Zoho Desk ticket using ZOHODESK

      Hi everyone, Currently, I am developing a Zoho Desk extension, and I am following the guide available at https://www.zoho.com/desk/extensions/guide/#ticket-object. While working with Zoho Desk, I have noticed that I can only retrieve the general information

    • AI & Zoho Recruit

      Hello, I guess we all are using AI in our personal and professional lives. Now, let's imagine. Recruitment is just a succession of stages and steps. For which step would you like to see AI implemented into Zoho Recruit ? I'll start : - Automatic translation

    • Workdrive and ChatGPT Team Synced Connectors

      Hi, we want to be able to integrate Zoho Workdrive with OpenAI’s ChatGPT Team plan. Google Drive and OneDrive both offer this, zoho please catch up asap. We dont want to have to put our company files in google drive, we want to allow chatgpt Team edition

    • widget url 404'ing

      I'm creating a widget for the first time. When I grab the url from the base url section of the widget builder and append /widget.html it 404's Just wrote a very basic test. I have a folder structure app.zip - widget.html --js/app.js /widget.html <!DOCTYPE

    • Unable to Edit Pick-List Items in Custom Project Field(s)

      I can edit most fields normally, but if I try to edit - in any way - a Pick List field, I just get this error: To be perfectly clear, I'm trying to edit an existing Pick List field (adding or removing items), not adding a new instance. If I rename it,

    • How to display results from zoho.crm.searchRecords in message window

      Hello, I've created a custom function which is linked to a custom button which pulls a date from our contacts module and searches a date field in our quotes module and returns all records matching the date. My issue is, how to I get this to display the

    • Domain Transfer

      Hello there! I wanted to know if I can transfer my domain from Zoho to other hosting providers or use a different hosting provider instead of zoho's services.

    • Select CRM Custom Module in Zoho Creator

      I have a custom module added in Zoho CRM that I would like to link in Zoho creator.  When I add the Zoho CRM field it does not show the new module.  Is this possible?  Do i need to change something in CRM to make it accesible in Creator?

    • New User - Opening Stock Aging Report

      I am setting up new client and am entering Opening Stock - created items and entered quantity/price details. Now the aging report is showing all the opening stock as new. How do I enter the Purchase Dates of these items so that I get accurate Inventory

    • Bulk Receive Multiple Purchase Orders

      Is there a feature or function that will allow you to bulk receive issued purchase orders? I have about 100 that need to be received from 5 years ago.

    • Manual Invoice

      How to create a Manual invoice, I need to enter Amount directly instead of (qty*Rate). our company is a service sector

    • Effective Inbox Organization: Folders vs Tags in Zoho Mail?

      I'm exploring the best ways to organize a busy inbox, especially when managing multiple clients or project using Zoho Mail. I’d love to know what works best for others: 1. Do you prefer **folders** (possibly with sub-folders) for each client or project?

    • Merging contacts and or accounts

      Hello, In a prior CRM we were able to merge contacts and or accounts.  We have turned on the function to stop multiple contacts with the same email, so we can prevent multiple contacts from happening, however, we now have multiple contacts that have the

    • Capture Reason for absence next to Campaign Member Status. Is there a reasonable workaround?

      I've reviewed the topics I could find to do with this but still couldn't find anything that satisfies our requirements: We would like to track a *reason* (picklist or text, doesn't matter which) why a Campaign Member (Lead or Contact associated with a

    • Zoho Learning Management System - Certificate Upload by Employees

      We are planning to enroll employees in courses which are hosted by coursera or similar sites. I want to share the links of those courses and also want employees to upload their completion certificate once they are done. Is this function possible in

    • Add RTL and Hebrew Support for Candidate Portal (and Other Zoho Recruit Portals)

      Dear Zoho Recruit Team, I hope you're doing well. We would like to request the ability to set the Candidate Portal to be Right-to-Left (RTL) and in Hebrew, similar to the existing functionality for the Career Site. Currently, when we set the Career Site

    • Button or Links order

      Is there a way to re-order the buttons or links that are created?

    • 'Pin' notes, so that specific ones are always visible at the top of the 'notes' tab.

      It doesn't appear Bigin has the functionality to 'pin' a note to then have it always show at the top of the notes tab section of a record. Often times we have a large number of records, but key information we may want to have easily visible to all at

    • Request for Subform Support in Zoho CRM Webforms

      Hi Team, I hope you're doing well. I would like to bring to your attention that currently, Zoho CRM Webforms do not support Subforms, which limits our ability to send forms that mirror the actual structure used within Zoho CRM. This feature is extremely

    • Formatting Mailing Labels

      I want to use the "Print Mailing Labels" function on the drop down list, but I am not seeing a way to change the formatting on the mailing labels. At the moment, the information that appears on the mailing labels ARE NOT mailing addresses, but random

    • Maxima Address on FSM Customer

      Im trying to add probably 50 customers from one company but couldn't make it since it has limit..how do i add the limit?

    • How to Track Inventory Usage from Zoho FSM to Zoho Inventory?

      Hi everyone, We’re currently working on integrating Zoho FSM with Zoho Inventory, and we’ve encountered a challenge we’re hoping the community can help us understand better. Here’s the context: When we create a Work Order in Zoho FSM that involves parts

    • View subform entries without viewing a record in Zoho CRM | Kiosk Studio Session #8

      In a nutshell Have you ever wanted to take a quick peek at a record's subform? Examples might be invoiced items in an invoice, ordered items in a sales order, or purchased items in a purchase order. Let's say you're viewing your list of invoices in Zoho

    • Next Page