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

• Kaizen #226: Using ZRC in Client Script

  Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In this

• Kaizen #222 - Client Script Support for Notes Related List

  Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore how

• 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

• Recent Topics

• Create Tasklist with Tasklist Template using API v3

  In the old API, we could mention the parameter 'task_template_id' when creating a tasklist via API to apply a tasklist template: https://www.zoho.com/projects/help/rest-api/tasklists-api.html#create-tasklist In API v3 there does not seem to be a way to

• Add multiple users to a task

  When I´m assigning a task it is almost always related to more than one person. Practical situation: When a client request some improvement the related department opens the task with the situation and people related to it as the client itself, the salesman

• iOS Books app shows filtered view after changing to All sales orders

  My boss often checks sales orders on his iPhone. The app is mostly working fine, but there's an ongoing issue: When switching between different filters (also called custom views on the web), going back to All doesn't often work. It typically gets stuck

• Problem with the blueprint flow.

  Scenario: 3 departments in a single environment: A-B-C agents from department 1 D-E-F agents from department 2 G-H agents from department 3 Since we've been using Zohodesk (2023), agents can assign tickets to the correct department using the blueprint

• Empowered Custom Views: Cross-Module Criteria Now Supported in Zoho CRM

  Hello everyone, We’re excited to introduce cross-module criteria support in custom views! Custom views provide personalized perspectives on your data and that you can save for future use. You can share these views with all users or specific individuals

• Recurring Invoices

  I'm looking to set up recurring invoices on a monthly basis, using GoCardless as a payment gateway. I've done this successfully, however there's a big problem with the Invoice Date and Due Date. We prefer to provide sufficient notice of collection (10

• Recurring Events Not Appearing in "My Events" and therefore not syncing with Google Apps

  We use the Google Sync functionality for our events, and it appears to have been working fine except: I've created a set of recurring events that I noticed were missing from my Google Apps calendar. Upon further research, it appears this is occurring

• Vorrei disdire l'abbonamento

  Vorrei disdire l'abbonamento, ma non trovo il modo. Mi assistete?

• Service line items

  Hello Latha, Could you please let me know the maximum number of service line items that can be added to a single work order? Thanks, Chethiya.

• Has anyone successfully gotten conditional rendering to work in Zoho Books Sales Order HTML PDF templates?

  I’m trying to hide a custom field box when the custom field is blank. The value placeholder itself works perfectly: ${salesorder.cf_distribution_reference_numb} If the Sales Order has a value, it renders correctly. Example: 45488045. But when I wrap that

• What's New in Zoho Inventory | April & May 2026

  Hello users, We're excited to roll out the latest Zoho Inventory updates for April and May 2026. These enhancements are designed to make your daily operations smoother and more efficient, from advanced inventory management and flexible pricing to automated

• Latest updates to Zia in Office Integrator

  Hello Zoho Office Integrator users! We’re pleased to share exciting updates to the proofing capabilities of Zia, our AI-driven writing assistant, in Office Integrator. With these updates, you can now get spell and grammar check in Brazilian Portuguese,

• How To Invoice Immediately for Future Subscription

  Hi, When a new subscription is created that has a future start date, Zoho Subscriptions does not invoice the customer until the start date of the subscription. Is there a way to immediately invoice the customer as soon as the subscription is created,

• Implementing Back Button Navigation in Zoho Creator

  Zoho Creator does not currently support a native Back button within forms, so implementing backward navigation requires a workaround. We recently implemented this in an application that was split into 9 modular forms. Since users needed to move between

• Deleted User Emails

  I need to delete a user as I need to re-use their license, but I'd like to keep all their emails that are attached to various contacts in the CRM. Their emails are hosted externally on an M365 license. Anyone any idea how best to engineer this? TIA

• In wiki editor, dragging an image fails

  Expected behavior: Within the WYSIWYG editor, we have been able to select and drag an image (that is already inserted in the page) to move it to a different position on the page. Current behavior: For a few days recently (possibly longer and I didn't

• Not able to see appointements when the territory permission is activated

  Hello, I created different territories to separate the various departments within the company that will be working on different projects. The issue I am currently experiencing is that when I enable territory-based permissions, I can see the work order

• Print multiple uploaded images in an HTML snippet in a Page

  I have a Form: Job_Preparation It stores details of each new item that must be built by the fabricators in our workshop. The form has a field: Documents I upload 4 image files to the Documents field. I want to print a sheet for our workshop staff with

• Quotes Module - import data

  Hello Zoho, is it possible to import Quotes records? I was trying and i have no results. Raport shows no data imported. Could you help me please how to do it?

• Introducing the new Zoho Announcements Hub

  Hello, Enterprise Support Community! We are excited to announce a new way to keep up to date with recent product releases and announcements for the Zoho apps you use on a regular basis. Introducing our new centralized location to bring together all Zoho

• Introducing Custom Columns in Forecasts in Zoho CRM

  Hello all, Forecasts in Zoho CRM help sales representatives, managers, and business stakeholders evaluate performance and plan future sales activities. While standard metrics such as Target, Achieved Amount, and Pipeline Amount provide a baseline view,

• Can Zoho CRM Emails be used in Zoho Analytics in any capacity?

  We're wanting to display details about Lead Activity in regular reports through Zoho Analytics but we're having difficulty integrating Emails at all. We'd like to be able to note when an email is received and when it is sent somewhere other than just

• Related list view for Assets

  We first set up all our parent assets in FSM and now we are adding child assets which are the parts for the parent assets. When under the customer related list, since it only displays 5 rows of data, I have to click through many assets to locate the parent

• Zoho Books - France

  L’équipe de Zoho France reçoit régulièrement des questions sur la conformité de ses applications de finances (Zoho Books/ Zoho Invoice) pour le marché français. Voici quelques points pour clarifier la question : Zoho Books est un logiciel de comptabilité

• Smart URL Determination

  I would like to see Vault implement some sort of "smart" URL determination. When one starts to add a new username-password combination from a new site, Vault brings in the exact URL of the page from which this is happening. All too often, it looks something

• Project Statuses

  Hi All, We have projects that sometimes may not make it through to completion. As such, they were being marked as "Cancelled". I noticed that these projects still show as "Active" though which seems counter intuitive. In fact, the only way I can get them

• Composite Services and Account Tracking

  I am looking to garner support/request the ability to make composite services. A quick search in the forums brings up multiple requests for this feature. I fail to see why an item is mandatory while services are optional. I also would like to see the

• Marketer's Space: Lists vs. segments—what's the difference?

  Hello Marketers, Welcome back to another post in Marketer's Space! In email marketing, reaching the right audience is just as important as crafting the right message. Yet many marketers often confuse lists and segments, using them interchangeably without

• Building a Multi-Step Form Experience in Zoho Creator Using Standard Forms

  Zoho Creator does not currently provide native multi-step form functionality. For applications with a large number of fields, a common requirement is to split data collection into manageable sections while maintaining a single application record. In this

• Add Video link to interview record

  Hi Team, we are having team members consistently go to the interview record to find the link for their upcoming meeting and have been confused that they have not been able to find them. When the interview is created can you please upload the link to the

• Zoho projects dependancies is a joke

  About to cancel our Zoho One subscription because Zoho Projects is a mess. Can't build a proper progream in it because the dependancies doesn't work properly. Can't believe this software is promoter as a project program when one can't even build a proper

• Wiki Add Attachment upload fails at about 15.3 MB

  I am seeing consistent "Error in uploading file" for files larger than about 15,430 kB. For 15,300 kB or smaller, no problem, but 15,430 kB or larger always fail. This is over numerous trials. My test files, to examine this problem, were generated by

• Stop Wasting Clicks: Let Us See All Notes in Quick View

  Hi Zoho Recruit team, I would like to suggest an improvement to the candidate/application experience in Zoho Recruit. Today, it is difficult to get a full picture of a candidate when working from the Quick View, since notes are split between: Notes related

• Zoho Books | Product updates | June 2026

  Hello users, Welcome to this month's roundup of what's new in Zoho Books! We have an exciting line-up this time. The highlight is the launch of the all-new France Edition with full ISCA compliance. We're also introducing features such as Layout Rules

• issue invoice for future subscription

  Hi, I selected the invoice at the date of subscription from the setting (since the alternative is to pre-set a date of a month) which is not my case. So, my question : Some times I need to create a subscription that will start at a future date but I need

• Associate emails from both primary and secondary contacts to deal

  We need to associate emails from multiple contacts to a deal. Please advise how this can be achieved. At present, only emails from primary contacts can be associated. Thanks

• How to set default reply email address depending on receipt email address

  Hi, I have a number of different customer support email addresses (info@XYZ.com, retuns@XYZ.com etc.) and want to set Zoho Desk so that the email address from which an agent replies is automatically defaulted to a predetermined address depending to which

• Writer is horrible

  Form filling is about unusable for complex forms! I am so tired of it.

• How to Migrate from MDaemon to Zoho Mail Account?

  Hi there, Zoho Mail is one of the most popular as well as leading competitor for several cloud email service providers. It is It provide cloud email service as well as desktop based email client. In recent years people are migrating from third party cloud servers to Zoho Mail. The reasons are plenty, i.e. the user interface, security, high performance and many countless amazing features. On the other hand MDaemon Mail (aka WorldClient) is also popular among cloud email servers. But there are some

• Trigger workflows from SLA escalations in Zoho Desk?

  Hey everyone, I’m currently working with SLA escalation rules in Zoho Desk and ran into a limitation that I’m hoping someone here has solved more elegantly. As far as I can tell, SLA escalations only support fairly limited actions (like changing the ticket

• Next Page