Kaizen #172 - Leveraging the 'crmAPIResponse' Object in Queries

Hello everyone!

Welcome back to another week of Kaizen!

We released the Queries feature sometime back and hope you have tried it out.

A little gist about this feature before we move on to our post.

Zoho CRM's Queries feature enables dynamic data retrieval from both CRM modules and external services, facilitating seamless integration and informed decision-making.

Key Components

• Sources: Pre-configured sources like Modules and COQL are available, with the option to add custom sources via REST APIs.
  
• Queries: Fetch data by selecting modules, writing COQL statements, or specifying REST API endpoints, headers, and parameters.
  
• Variables: Incorporate variables in criteria, COQL statements, and endpoints to pass dynamic values during execution.
  
• Schema: Auto-generated schemas define the structure of query responses, with editable paths, field types, and labels for customization.
  
• Serializer: Utilize JavaScript to manipulate and customize query responses, ensuring data is in the desired format for further processing.
  

Types of Queries

• Modules: Retrieve records by selecting specific modules and fields, applying conditions to filter data as needed.
  
• COQL (CRM Object Query Language): Write SQL-like queries to fetch data, supporting complex operations like joins and aggregations.
  
• REST API: Fetch data from external services by specifying endpoints, headers, parameters, and connections.
  

With the Queries feature, you can efficiently access and display relevant data within Zoho CRM, enhancing workflow efficiency and decision-making capabilities.

A little insight into Functions before we dive into today's Kaizen!

Functions, Queries, you get the connection, right? Read on!

Many of us use Functions in Zoho CRM extensively to perform our business logic and customize the way things work in Zoho CRM. You can use Functions in blueprints, workflows, Circuits etc.

Let's say you have a function that gets the employee records from the Employees module. Technically, the function executes an API call or an integration task, and gives a response.

The response can be a string or map(JSON), depending on how the function is written and where it is used. Since functions can be used in many places, the same response format may not be the right one to be used in a circuit or a workflow.

This is where the genie 'crmAPIResponse' object comes into picture!

The power of the 'crmAPIResponse' object

The crmAPIResponse object to be returned in the CRM function should encapsulate the response in a way that it can be used in Queries, Circuit, workflow etc. The details needed are encapsulated as a map. It should include details like crmStatusCode, status, message, body in order to construct the desired format for handling data and customizing the error handling logic.

Let's consider the following example function where we use the getRecordByID integration task.

The response of the integration task contains all the fields in that module, but we want only certain parts of the response JSON and also add custom error messages, to be used in other components like Queries, Circuits, etc,.

Here is the code.

{ leadId = "3652397000018025772"; // Replace with a valid Lead ID // Initialize customAPIResponse map customAPIResponse = map(); // Fetch lead details crmResponse = zoho.crm.getRecordById("Leads", leadId); // Log the raw response for debugging info "CRM API Raw Response: " + crmResponse; // Validate and process the response to include only the required fields if (crmResponse != null && crmResponse.containsKey("id")) { // Extract required fields filteredData = map(); filteredData.put("id", crmResponse.get("id")); filteredData.put("Last_Name", crmResponse.get("Last_Name")); filteredData.put("Email", crmResponse.get("Email")); customAPIResponse.put("crmStatusCode", 200); customAPIResponse.put("status", "success"); customAPIResponse.put("message", "Lead data retrieved successfully."); customAPIResponse.put("body", filteredData); // Include only filtered data } else { customAPIResponse.put("crmStatusCode", null); customAPIResponse.put("status", "error"); customAPIResponse.put("message", "Invalid or null response from Zoho CRM API."); customAPIResponse.put("body", null); } // Return the customAPIResponse return {"crmAPIResponse": customAPIResponse}; }

Here, you can see that we have parsed the response of the integration task to get the Last_Name, Email, and record ID using the crmResponse.get("field_API_name") statement and constructed the customAPIresponse object using the customAPIResponse.put("key", "value") statement.

The statement return {"crmAPIResponse": customAPIResponse}; returns the response body as depicted in the previous statements.

Response to the info "CRM API Raw Response: " + crmResponse; statement

"CRM API Raw Response: {"Owner":{"name":"Patricia Boyle","id":"3652397000000186017","email":"p.boyle@zylker.com"},"$field_states":null,..}}}

Response of the return {"crmAPIResponse": customAPIResponse}; statement

{     "crmAPIResponse": {         "crmStatusCode": 200,         "status": "success",         "message": "Lead data retrieved successfully.",         "body": {             "id": "3652397000018025772",             "Last_Name": "Math",             "Email": "math@gmail.com"         }     } }

Error response

{     "crmAPIResponse": {         "crmStatusCode": null,         "status": "error",         "message": "Invalid or null response from Zoho CRM API.",         "body": null     } }

You can see that we have used the crmAPIResponse object to get only the required keys from the response and constructed a much simpler response.

Refer to our help page on Response Object for more details.

Finally, to today's Kaizen!

We've established that you can use the crmAPIResponse object to construct responses in a way that's suitable to be consumed at another place like a circuit or a workflow.

We also know that Queries allows you to have sources of the REST API type to fetch data from various sources. This means that you can have a standalone function that is enabled as a REST API as a source in Queries.

Let's see an example.

There is a simple function that uses the getRecords integration task to get the records from the Employees module.

I have used the crmAPIresponse object to construct a response as shown in the following code.

string standalone.getRecords() { result = zoho.crm.getRecords("Employees"); response = Map(); response.put("status_code",200); response.put("body",{"code":"success","details":result,"message":"function executed successfully"}); return {"crmAPIResponse":response}; }

The response of this function is a string in the crmAPIResponse object as shown in this image.

1. Save this function and enable REST API.
   
   
2. You can see that the domain is https://www.zohoapis.com. To be able to use this in a Query, register this domain in Trusted Domain.
   
   
3. To create a REST API type source, you must add the source. Go to Setup > Developer Hub > Queries > Sources tab.
4. Click Add Source and give the details like the name, base URL, headers, and parameters under the Information section.
   
   
5. Click Save.
6. Go to the Queries tab and click Add Query.
   
7. For Source, choose the source you just added.
   
8. Under Information, enter the name, API name of the query.
   
9. For the endpoint, enter the API Key URL of the function.
   
   
10. Enter the parameter name and values in the Parameter field.
    
11. Click Add Serializer if you want to serialize the response. In this example, I have serialized the response to include only the Name, Email, and Position fields in the output. The result contains the 'body' object that we returned in the crmAPIResponse object of the function.
    
    
    
    
12. Click Save to save the serialization.
    
13. Click Next to view the schema of the query. Make changes as required.
    
14. Save the query.
    

You can now use this query in Canvas or associate it with Kiosk to solve your business needs.

Let us see how the crmAPIResponse object in the function affects the response of the query.

Query with the function without crmAPIResponse:

Let's consider that the function getRecords() does not use the crmAPIResponse object. In that case, the function returns a response that is a string. This response string cannot be serialized or used elsewhere.

Schema of the query without crmAPIResponse:

Query with the function with crmAPIResponse and serialization:

The same getRecords() function that uses the crmAPIResponse object allows you to construct the response as JSON. You can serialize this response easily and use it in a circuit, query, workflow etc.

You can see here that the response is now a JSON.

Schema of the query with crmAPIResponse:

In conclusion, you can use the crmAPIResponse object in Functions to construct the desired response and use the REST API-enabled function as a source in Queries.

Leveraging the advantage of the crmAPIResponse object in functions and using it in Queries increases the prospect of solving many more business cases easily and customize more efficiently.

We hope you liked this post and found it useful. Let us know your thoughts in the comments.

If you'd like us to cover any other topic in this series, feel free to comment or reach us at support@zohocrm.com.

Cheers!

------------------------------------------------------------------------------------------------------------------------------------------------

More enhancements in the COQL API are now live in Zoho CRM API Version 7. Check out the V7 Changelog for detailed information on these updates.

See Also

• Related Kaizen - Handling Variables in Queries, Serialization and Schema Management in Queries 
• Queries in Zoho CRM
  
• Functions in Zoho CRM
  
• Response Object in Zoho CRM
  
• Previous Kaizen - FAQs on COQL API
  
• Kaizen Directory
  

• Topic Participants

• Shylaja S

  

• Zsolt Simon self-employed

• Sticky Posts

• Kaizen #217 - Actions APIs : Tasks

  Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.

• Kaizen #216 - Actions APIs : Email Notifications

  Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are

• Kaizen #152 - Client Script Support for the new Canvas Record Forms

  Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved

• Kaizen #142: How to Navigate to Another Page in Zoho CRM using Client Script

  Hello everyone! Welcome back to another exciting Kaizen post. In this post, let us see how you can you navigate to different Pages using Client Script. In this Kaizen post, Need to Navigate to different Pages Client Script ZDKs related to navigation A.

• Kaizen #210 - Answering your Questions | Event Management System using ZDK CLI

  Hello Everyone, Welcome back to yet another post in the Kaizen Series! As you already may know, for the Kaizen #200 milestone, we asked for your feedback and many of you suggested topics for us to discuss. We have been writing on these topics over the

• Recent Topics

• Unveiling Zoho Sites 2.0 - A new dimension in website building

  Dear Zoho Sites Users, We are thrilled to announce the launch of Zoho Sites 2.0 today! This refresh represents a significant step forward in the capabilities of Zoho Sites and is crucial for creating a lasting and positive impact on our customers' businesses.

• Weekly Tips : Make collaboration effortless with Whiteboard in Zoho Mail

  Working with your team often means switching between emails, notes, and other applications just to explain an idea. Maybe you are trying to sketch a layout, plan a workflow, or quickly brainstorm ideas—with text alone, things can get confusing. So how

• Zoho Projects - Update Feed via API

  Hi Projects Team, Please consider adding an API to allow update and retrieval of messages to the Feed. Thank you

• Rich-text fields in Zoho CRM

  Hello everyone, We're thrilled to announce an important enhancement that will significantly enhance the readability and formatting capabilities of your information: rich text options for multi-line fields. With this update, you can now enjoy a more versatile

• Zoho Projects - Email Notifications for Feed Updates

  Hi Projects Team, I'm working with a client who wants a simple way to communicate with their customers on projects. Getting the customer to add comments to Tasks or Bug records is not ideal, as we need a way which is easy with minimal training, and has

• Hide fields only for creation

  Hello, I'd like to hide some fields only during the creation of a contact in Zoho CRM. In fact I have some fields that are automatically calculated thanks to an automation, so when my users create a contact I don't want them to fill those fields. I know

• My go to On Load Client Script - Fast, efficient, and works for ALL profiles; Hides everything except initial fields

  This is my on Load client script that I use for Create pages. I use a modified version for Edit and Display pages which you can create yourself using the same basic structure that I will give you below. First up, the script. Below that will be an explanation

• Cliq iOS can't see shared screen

  Hello, I had this morning a video call with a colleague. She is using Cliq Desktop MacOS and wanted to share her screen with me. I'm on iPad. I noticed, while she shared her screen, I could only see her video, but not the shared screen... Does Cliq iOS is able to display shared screen, or is it somewhere else to be found ? Regards

• Zoho Sites "pages" management page

  I have 80 plus pages on zoho sites. When I go to the "pages" link to view and edit pages, They are not in any kind of order, so I spend lots of time searching for pages when I need to edit or create new. How can I change the view order of all my pages

• Introducing the all-new email parser!

  Greetings, We are pleased to introduce to you, a brand-new, upgraded version of the Zoho CRM Email Parser, which is packed with fresh features and has been completely redesigned to meet latest customers needs and their business requirements. On that note,

• Exciting Updates to the Kiosk Studio Feature in Zoho CRM!

  Hello Everyone, We are here again with a series of new enhancements to Kiosk Studio, designed to elevate your experience and bring even greater efficiency to your business processes. These updates build upon our ongoing commitment to making Kiosk a powerful

• Zoho Projects - Refine Access to Collaboration Menu

  Hi Projects Team, I noticed that Calendar, Chat and Meeting menu options in the Collaboration section are visible to client users, even when they don't have access to the features. This could be confusing and frustrating, because if it's there you expect

• Zoho Projects - Add Feed to Project Tabs

  Hi Projects Team, I'm working on a lightweight communications requirement for one of my customers in relation to communicating with their client users via Zoho Projects. I noticed that the Feed is only available in the Collaboration section, but you can

• Zoho Books Finance Modules Not Accessible in Zoho CRM Mobile App

  We have integrated Zoho CRM with Zoho Books using the Zoho Finance Suite integration. In the CRM web version, we can see the Finance modules (Estimates/Quotes, Invoices, Sales Orders, Items, Payments) and are able to create invoices and quotes directly

• Zoho CRM Kiosk Upload Files

  Hello all, We are trying out Kiosks at the moment to see where it can fit best in our business. We are still a bit off in the application but lets say we will sort this out. My question is the following - when I create a Kiosk I can add "File Upload"

• Connecting zoho creator to zoho writer to send prefilled documents

  i will paste the worflow below // Get user's submitted data from the form userSalary = input.Current_Salary; userCIBIL = input.CIBIL_Score; userEmail = input.Email; userName = input.Name; // You need to get the Document ID from the URL of your Zoho Writer

• Extracting Images from a Zoho Creator Report into a Pages

  If you’ve uploaded images in a form and can see them in your report, you might also want to display those same images inside a Page (custom HTML page). This is useful for dashboards, profile pages, or any place where images should be visible dynamically

• How do I change a form's name? Why isn't this more intuitive?

  Can someone please let me know how to change a form's name?

• Zoho is blocking emails I subscribe to from one sender

  About 4 months ago I stopped receiving newsletters that I subscribe to from @thedispatch.com. They tell me that zoho's server is blocking them. I've added them to my contacts list, but they're not even reaching my inbox. I don't know how to troubleshoot

• Introducing Formula Fields for performing dynamic calculations

  Greetings, With the Formula Field, you can generate numerical calculations using provided functions and available fields, enabling you to derive dynamic data. You can utilize mathematical formulas to populate results based on the provided inputs. This

• Inactive Items - Make Less Prominent by Default

  Currently, when one marks an Item as "Inactive", it really doesn't do much of anything to hide it or get it out of the way. Search and reporting within Finance should, by default, hide inactive Items from standard reports, searches, etc. If one specifically

• Items should display under specific warehouse

  I have configured the multi warehouse but it show all the items under all warehouse which is not correct according to our business logic, so i want that items should only display under that specific warehouse not under all the warehouses not even with zero quantity. Some items should be common but not all so is there any option for that purpose so i can specific the items to its warehouse. Regards

• Zoho Analytics Bulk Api Import json Data

  HI, I’m trying to bulk-update rows in Zoho Analytics, and below are the request and response details. I’d like to understand the required parameters for constructing a bulk API request to import or update data in a table using Deluge. Any guidance on

• E-Invoicing in Belgium with Zoho Billing

  Starting January 1, 2026, Belgium is introducing mandatory electronic invoices (e-invoicing) for all B2B transactions between VAT-registered businesses. Invoices and credits notes must be exchanged in a prescribed digital format. How E-Invoicing works

• Convert HTML to PDF & Send as Email Attachments in Zoho Creator (Deluge)

  This approach is useful for sending welcome letters, instructions, or promotional offers after order creation. // 1. Define the variables using the submitted input customerName = input.Customer_Name1; orderID = input.ID; customerEmail = input.Email_Address; //

• Auto-fill New Row with Previous Row Values

  rowsize = input.Order_Items.count(); for each row1 in input.Order_Items { rowsize = rowsize - 1; if(rowsize == 1) { row.Door_Model = row1.Door_Model; row.Door_Color = row1.Door_Color; row.Materials = row1.Materials;

• I am facing a problem with an if-else condition

  If I use if, else if, and else conditions in Deluge with the same variable name, sometimes the variable causes an error because the same variable name is present in every block

• When I click on PDF/PRINT it makes the invoice half size

  When I click PDF / Print for my invoice in Zoho Books, the generated PDF appears at half size — everything is scaled down, including the logo, text, and layout. The content does not fill the page as it should. Could someone advise what causes Zoho Books

• Python - code studio

  Hi, I see the code studio is "coming soon". We have some files that will require some more complex transformation, is this feature far off? It appears to have been released in Zoho Analytics already

• API question - adding a thread to an existing ticket

  Hi Is there an API function for the customer to add to an existing ticket thread? example, customer puts in new support ticket. support replies and ask for more details. customer replies with more details -what api function is used for this (will add record append to same ticket number?) Thanks

• search and Smart Bar both missing in Mail

  One of the users on my account does not have the search bar at the top right or the Smart Bar at the bottom left of the desktop Mail app. Any ideas how to get those back?

• Why is Zoho Meeting quality so poor?

  I've just moved from Office 365 to Zoho Workplace and have been generally really positive about the new platform -- nicely integrated, nice GUI, good and easy-to-understand control and customisation, and at a reasonable price. However, what is going on

• Items Below Reorder Point Report?

  Is there a way to run a report of Items that are below the Reorder Point? I don't see this as a specific report, nor can I figure out how to customize any of the other stock reports to give me this information. Please tell me I'm missing something s

• Qwen as the default open source Generative AI model for Zia

  Hello everyone, Zia Generative AI is transitioning from Llama (8B parameters) to Qwen (30B parameters) as the default model. This means that users who were using Llama as a GenAI service will now use Qwen. This upgrade was made with a vision to enhance

• Calendar week view: Today + 6

  Is there anyway to have the calendar change dynamically based on the date? Due to the amount of events, we only display a week at a time, but towards the end of the week, we can no longer see ahead to next week (without changing it manually every time).

• How to restrict user/portal user change canvas view

  Hi , I would like to restrict user / portal user change their canvas view because I hide some sensitive field for them. I dont want my user switch the canvas view that do not belong to them But seems Zoho do not provide this setting?

• E-Invoicing in Belgium with Zoho Books

  Starting January 1, 2026, Belgium is introducing mandatory electronic invoices (e-invoicing) for all B2B transactions between VAT-registered businesses. This means that invoices and credits notes must be exchanged in a prescribed digital format. How E-Invoicing

• E-Invoicing in Belgium with Zoho Inventory

  Starting January 1, 2026, Belgium is introducing mandatory electronic invoices (e-invoicing) for all B2B transactions between VAT-registered businesses. Invoices and credits notes must be exchanged in a prescribed digital format. How E-Invoicing Works

• Enhancement Request for Multi-Asset Work Order Feature

  Hello Latha, Thank you for your continued support. The multi-asset Work Order feature is extremely helpful. I did some testing based on our requirements, and during the process, I noticed a few areas where we need your team’s support to improve the feature

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

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

• Next Page