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

    • Introducing real-time document commenting and collaboration in Zoho Sign

      Hi, there! We are delighted to introduce Document commenting, a feature that helps you communicate with your recipients more efficiently for a streamlined document signing process. Some key benefits include: Collaborate with your recipients easily without

    • Adding Photos Into Form (as a form creator)

      As the form creator, is it possible to add images to my form? (I don’t mean adding an image upload field, but rather inserting a JPG file into the form so that users can view the image.)

    • [Training] AI-Powered Application Development Bootcamp 2.0 - Zoho Creator

      Hello everyone, Ready to take your app-building skills to the next level with the power of AI? We’re excited to invite you to AI-Powered Application Development Bootcamp 2.0—a 90-minute, live training session designed to help developers, business users,

    • What is the easiest/fastest way to attach an email or PDF to a Zoho record?

      Hi everyone, We use Outlook with Office 365 and have the need to either ideally attach a .msg email directly to an account or custom module in Zoho, or if not attach just the PDF that would be sent in that email. The Zoho plugin is very basic for Outlook

    • Free webinar! Close deals faster with Zoho Sign from Zoho CRM

      Hello, Are you tired of chasing down signatures and getting stuck with paperwork delays in your sales process? With the seamless integration between Zoho Sign and Zoho CRM, you can create and send documents for signing online, close deals faster, and

    • Files stores in Library Marketing Automation

      Hi, How can i switch from card view to list view in Marketing Automation My Files.?

    • Paid for upgrade and no change

      I paid the $24.99 rate to upgrade to Pro version and no change when I signed out and signed back in.

    • Issue with Code Snippet Styling Overlap in Zoho Landing Page

      Dear Support Team, I have encountered an issue on the Zoho Landing Page while working with code snippets. When I try to create a custom script and add HTML, CSS, and JavaScript within the code snippet, the styling appears to overlap and affect other code

    • Adding yearly Calander

      How to add Yearly calander and employee data from admin console

    • Zoho Leave Policy > Portugal maternity Leave 120 days or 150 days

      Hello All In this Portugal maternity Leave policy, the government allow employee to apply 120 days they will have 100% paid salary if they apply 150 days they take 80% of the paid salary minimum 1 days and maximum 120 days or 150 days Should i setup this

    • Feature Request - Copy Reschedule Link

      Hi Bookings Team, I had a client contact me today, to let me know that she can't make a meeting she booked this week. I can't remember if I included a reschedule link in email notifications, but I was thinking that it would be great if I could just open

    • eCommerce ZUG Virtual Meetup – Critical Role of e-Signatures in eCommerce

      Hello there! Are you in the ecommerce industry and looking for a secure, compliant e-signature solution to handle all your paperwork? From vendor onboarding and supplier contracts to internal HR and finance workflows, speed, scalability, and customer

    • Zoho Desk iOS app update: Archived ticket list view

      Hello everyone! In the latest iOS version(v2.10.7) of the Zoho Desk app update, we have brought in support to access the 'Archived Ticket views' on the 'Ticket Views' screen. Tickets that have been Closed and inactive for 120+ days will be automatically

    • Chart of Accounts

      Is it possible to reorder chart of accounts manually? Currently, when creating new sub accounts accounts, they appear in order they were created i.e. not in alphabetical or numerical order based on manually assigned account codes. It's very messy! Also,

    • Zoho People Candidate Unable to see Non Admin Data

      Hello All I have assign this user as specific user as Group CEO and have access all legal entity, business unit division When i login to the user and look into onboarding i do not see any data in the candidate view This is the admin view that i have 2

    • Issues With Image Formatting when Importing Word Documents as Articles

      Hello, I am having formatting issues when importing .docx files into articles. The documents look fine on Word, but once they are imported into an article, the images will overlap text and other images. Occasionally there will be added space between images

    • ZOHO COMMERCE 2.0 – Réinventer la vente, repenser la valeur

      Il y a cinq ans, nous avons lancé Zoho Commerce pour accompagner les entreprises dans la vente en ligne. À cette époque, notre objectif était clair : simplifier l'e-commerce. Aujourd’hui, le marché a évolué, tout comme les attentes des entrepreneurs.

    • Business hours in reports

      Hi. If I activate the business hours for my tickets. Does it affect in reports? I mean, if before, without working hours a ticket comes in on a Monday and closes the following Monday, in the resolution time in working hours I get 7 days. I want to know

    • Zia Field Prediction - Unable to Validate Dataset Entries

      Lastly, whenever we want to create a new field prediction, the status gets stuck in Incomplete and when I try to annotate tickets, I get an error message saying "Unable to validate dataset entries." I've tried deleting and recreating the prediction, but

    • Using an article already existing in Zoho Desk KB as a resolution for another tickets

      Hi, I've read about the Resolution tab of the Tickets and the ability of adding a Resolution to the Knowledge Base so that both agents and customers be able to access this information. However, and considering several tickets may be solved by following the same procedure, here's my question: if, for a ticket, I solved it and added the way I solved it as an article in our KB, is it possible to grab that article and use it as a resolution for another tickets with similar characteristics? If it's not,

    • How to create knowledge base article from api?

      How to create knowledge base article from api?

    • Disabling Smart Writing Assistant

      Hello, I've found this article when looking to disable the Zoho Smart Writing Assistant in our Zoho Desk environment. I appreciate that the article is for another Zoho solution, however, I was still unable to disable this feature! Could we please have

    • Append tags to records on import

      Dear Customers, We hope you're well! Tags in Zoho CRM are humble labels you can earmark your records with for quick classification and recognition. You can tag records one by one when you have only a few records to update; you can automate tagging when

    • "Recently Changed Payload Format" for webhooks in Zoho Billing

      We are seeing a message about recently changed payload format for webhooks in zoho billing. I cannot find any notification about this change can you give me more information on this?

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

    • Zoho People Created a UBO/Group CEO Profile to view all employees

      Hello All I have created a specific role UBO/ Group CEO Profile that is able to access to view all employees information Applicability i have input all the legal entity, business unit and division which most employees are added. I have also given access

    • We've updated the webhook payload format

      We’ve updated the default payload format for webhooks as part of our ongoing efforts to standardize the webhook format across Zoho Finance suite of applications. Note: This change is also applicable for the webhooks configured from the Developer Portal.

    • Zoho People > Access of Left Menu

      Hello All May I check how do i activate or de-activate of the left menu for users do i control via role or specific role? I have assign a user to Team member

    • Custom Button - Location Choice is not changeable in creation

      I created a custom button for the Tasks module that calls a function to streamline mass updates of closing tasks as "complete". I want to place it in either the utility menu or the mass action menu, but when I create the button the "select page" field

    • Workflow on Clone

      Hello. I'm interested on creating a workflow on a clone of a record in the Price_Books module that will clone also all the related Products and associate the new ones with the new Price_Book. My problem starts with that there's no On Clone event, only

    • How can I create a button in a widget that pops up a form created in ZOHO Creator when clicked?

      I know that using HTML snippets, clicking the button can pop up the form. However, the same code does not work in the widget. <button><a href="#Form:form2?zc_LoadIn=dialog">Add</a></button>

    • Introduce an option to hide the form title

      My feature request is to include an option to hide the form title. At the moment it is possible to hide the header. In some cases I do want to show a logo image in the header but not the form title. As a workaround I have tried disabling the header and

    • 関連トピックから配信リストをつくる

      ZOHOキャンペーンの既存の連絡先リストを関連トピックで絞り込んで、配信リストを作成する方法があれば、教えてください。

    • Zoho Mail not working

      Anyone else had the issue where emails wont send from either the desktop CRM or the mail app? It just says "syncing" then "failed". I deleted it and tried to access emails through the CRM on my phone (fold) but they dont show. It seems it is impossible

    • Shorten one URL but not all

      I have read that I should be able to click on the shorten link button at the bottom of the post window and shorten just one URL. But it does all of the URLs in my post. I want only one shortened. Not sure what I'm missing. Any help appreciated.

    • What is Zoho Marketing Plus?

      As if there wasn't enough confusion with SalesIQ, CRM, Campaigns and Marketing Automation, now we have Marketing Plus too. Can somebody from Zoho please give us a comparative list of features that are in Marketing Plus compared to what's in Marketing

    • I didn't receive my domain verification mail

      I didn't receive my domain verification mail 

    • Creating a new deal with specific layout and pipeline

      I am trying to create a button which creates a new deal for a particular account. It needs to be assigned a specific layout and pipeline. It seems like it should be really simple but I've been struggling to get this to work all day, can anyone help?!

    • Announcing New Features in Trident for macOS (v.1.21.0)

      Hello everyone! Trident for macOS is here with interesting features to elevate your workplace communication and productivity. Let's take a quick look at them. Get better visibility for concurrent events. Quickly compare and manage simultaneous events

    • Modifying Product Details

      I am in the process of setting up new products in Zoho Commerce and have encountered a few problems: 1) Tabs It seems that Product Details pages do not have the ability to create Tabs. eg:  https://www.thedebugstore.com/tp240141-aardvark-usb-i2c-spi-host-adapter-total-phase.html

    • Next Page