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:





    • 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

    • Is it possible to hide fields in a Subform?

      Since layout rules cannot be used with Subforms, is there another way, or is it even possible, to hide fields in a subform based on a picklist fields within said subform? For example, if the Service Provided is Internet, then I do not want to see the

    • Weekly Tips :Instantly find what you need with Attachment Viewer

      Your inbox must be packed with project emails, shared notes, and scattered attachments. You are looking for one specific file—a presentation slide or maybe a media clip from a team update—but don’t want to dig through endless email threads or switch between

    • Putting Watermark on Zoho Sheet

      Can this be done?

    • Missing Zoho Desk integration option for form workflows

      According to the help page "Configure Zoho Desk integration in form workflows" we should be able to select Zoho Desk as an integration target but when I open the integrations list then Zoho Desk is not being listed in it. We are on the Premium plan which should already support Zoho Desk integrations.

    • Gantt for 2 or more projects

      Hello, I'm trying the free version of your produtc. It is veryyy good!!!! I don't know if in the Standard plan, I can overview a Gantt Graph for 2 or more Projects Milestone. This would be very helpfull for managing teams and taking decisions about who I will assign a task to. In the paid plan Do I have this possibility? Thank you.

    • Integrating a Zoho Project Gantt Chart into Reports

      Is is possible to integrate a Zoho Project Gantt Chart into a Zoho Report Dashboard. I am in the process of creating Project Status Dashboards for the projects that we track in Zoho Projects and I would like to incorporate the gantt chart within Reports.  Please let me know! Thanks

    • ZOHO BOOKS - EXCESSIVELY SLOW TODAY

      Dear Zoho Books This is not the first time but it seems to be 3 times per week now that the system is extremely slow. I work on Zoho Books 95% of my day so this is very frustrating. Zoho you need to do something about this. I have had my IT guy check

    • Gantt Chart - Zoho Analytics

      Are there any plans to add Gantt Charts capabilities to Zoho Analytics?

    • Displaying related quotes in sales order and back

      Hi, My colleague liked to see to which sales orders, the quote has been converted. Quote shows Invoices, but not SO. Same, they would like to see the quotes in the sales order, as they can see invoices, packages, shipment, How can we achieve this ? Thank

    • Tip of the Week #71–Auto-move incoming messages to the right inboxes with keywords

      We all know that customer-facing teams, especially your sales and support teams, can’t afford to miss even a single customer conversation. But sometimes, sales queries or support requests can easily get lost in a crowded inbox or even end up in the wrong

    • Clearing Fields using MACROS?

      How would I go about clearing a follow-up field date from my deals? Currently I cannot set the new value as an empty box.

    • Migrating a Zoho Forms form into Zoho Creator

      Hi, How can I migrate my Zoho Forms form into Zoho Creator? Thanks. Truly, Emad

    • Is 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, from

    • is 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 assign

    • Problem 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 items

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

    • CRM 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 Varun

    • How 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, Jonathan

    • Analytics for notes created

      Is there a way I can see how many notes were created per day? Via reporting or analytics?

    • No TDS Deduction

      In some of our case, where we are reselling items at the same rate we purchased. In this scenario, Indian IT Law has a provision to request customer not to deduct TDS if the transaction value is same. TDS is paid by us (intermediary reseller) before we

    • Cannot 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 add

    • More 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 certain

    • Calls 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" for

    • Image 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 building

    • Power 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 automate

    • Lead 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 detailed

    • Range 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 spreadsheet

    • Has 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 thing

    • populate 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 you

    • SAP S/4 HANA to CRM Integration - change the SAP Client ID

      Hi I am trying to push the business partners from SAP S/4 HANA to ZOHO CRM module. The SAP Client ID is 421 in my case....kindly let me know how do I specify the sap client because it's a dropdown with specific values as of now. Thanks Ravi Aswani

    • Staff rules

      Hi! Do you people know what are the default staff rules when a new booking is created? We have two staff members in my team (me as the admin, and my employee). As we share the same services, I'm wondering how Zoho will pick the staff for new apointments.

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

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

    • How 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 Event

    • Adding 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!

    • Next Page