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

• Introducing SlyteUI : From Idea to a Working Interface in Minutes

  Hello everyone! Are you spending hours building basic UIs? Does even the smallest customization feel like a major task? CRM customization should feel intuitive and straightforward, not time consuming or exhausting. SlyteUI makes this possible by simplifying

• How to install Widget in inventory module

  Hi， I am trying to install a app into Sales Order Module related list, however there is no button allow me to do that. May I ask how to install widget to inventory module related list?

• Sync Task Status from Zoho Projects to Zoho Desk

  Hi Zoho Desk Team, Hope you’re doing well. We’re actively using the Zoho Desk–Zoho Projects integration, which helps our support and project teams stay aligned. However, we noticed that when we change a task’s status in Zoho Projects, the change is not

• Is there a way to sync Tags between CRM and Campaigns/Marketing Hub?

  I wonder if there is a way to synch the tags between CRM and Marketing-Hub / Campaigns?

• Host not reachable when sending

  For few partner that I send regular emails now got error and they don't receive emails Temporary failure fam-xxx.hr/185.xx.xx.xxx Host not reachable. Have more than 20 mails in https://mailadmin.zoho.eu/cpanel/home.do#mailSettings/retryEmail please

• Negative Quantity on an Invoice

  I need to be able to put a negative quantity on an invoice in books and inventory. Example, customer is buying part A, which has a removeable part, part B. Customer wants Part C which replaces Part B. We swap them for the customer. On an invoice we should

• Button Duplication when emails forwarded or replied

  When I create a new email template in campaigns and send it out it looks fine to all the users, however if that email is then on forwarded or replied to then all buttons within the email duplicate.  See below The one on the left is the original one.

• Super Admin Logging in as another User

  How can a Super Admin login as another user. For example, I have a sales rep that is having issues with their Accounts and I want to view their Zoho Account with out having to do a GTM and sharing screens. Moderation Update (8th Aug 2025): We are working

• What's New in Zoho POS - March 2026

  Hello everyone, Welcome to Zoho POS’s monthly updates, where we share our latest feature updates, enhancements, events, and more. Let’s take a look at how March went. Zoho POS Android app with Arabic and RTL Support for Saudi Arabia We have launched the

• Zoho Projects Android and iOS app update: Custom modules

  Hello everyone! We are excited to introduce the custom modules within the Zoho projects mobile app. Custom modules allow you to define your own entities with relevant fields, enabling you to capture and manage information specific to your workflows beyond

• Zoho Projects iOS app update: Flag type(Internal/ External) information in Task list header

  Hello everyone! We have now included the Flag(Internal/ External) type information on the Task list header within the Tasks listing screen of the Zoho Projects iOS app. This enhancement enables you to distinguish between the internal and external tasks

• How to close an estimate ?

  Hello, I have created estimates, and converted them to invoices to get 50% payment. Now I have 2 cases where the estimate stills shows status partially invoiced, however: 1. for one of them, project stopped half way, so the remaining part will never be

• Will Zoho Search work with Zoho Learn

  Currently, Zoho Search only works with Zoho Wiki which will be phased out.  Moving forward, will Zoho Search be enabled for Zoho Learn? Thanks.

• No possibility to make acknowledgement checkbox be not preselected and mandatory

  There is functionality available to enable a checkbox for the acknowledgment of the user confirming that the lesson has been completely read and understood. Currently, it is pre-selected but not mandatory. This leads to learners simply ignoring it. The

• Ability to modify what displays in calendar invite?

  I am a long time calendly user and want to make the switch to bookings.  I understand that there is not currently a meets/hangouts integration, is one on the roadmap? Is there anyway I can modify the calendar invite to include the meet link?  I can add it to the emails no problem, but I would also like it to display on their calendar.  Is there some work around I can do to get it on the calendar?  Also am I able to modify the calendar event title?

• since the new interface of ZOHO writer can't turn of automatic reminder option for merge documents

  Since the new interface of ZOHO writer I have this problem. I have a large set of templates that I use to send documents to ZOHO Sign. But now in all those templates the box for Sending reminders is ticked, which i don't want. But even if I untick the

• Global "Search" in FSM

  I'm missing the global Search function like in CRM. This should save us a lot of time. We don't now upfront if the customer is a Contact or a Company. So now we have to guess in what module to start a search/filter. Also looking up an address, phone number,

• Set Default Status of Assembly to "Assembled" When Entered in UI

  I've just discovered the new "confirmed" status of Assemblies within Inventory. While I understand the intent of this (allowing for manufacturing planning and raw material stock allocation), it was initially confusing to me when manually entering some

• Announcing Zoho Sheet desktop app for macOS and Windows (Beta)

  Hello Sheet users, We know you’ve been waiting for this one. It has always been the top priority on our roadmap to provide a single native desktop app for macOS and Windows that works both online and offline. Today, we are excited to announce that the

• Unable to Access /crm/v7/taxes – OAuth Scope Mismatch in Zoho CRM API

  I am currently integrating Zoho CRM (v7 API) with our system and I need clarification regarding the Taxes API and OAuth scopes. Context: We are creating Quotes via the API (/crm/v7/Quotes) Each quote contains line items with taxes (e.g., TVA 19%, 10%,

• Reading emails sent from Zoho

  Hi there, How do I view an email sent from Zoho, for example an email which contains an estimate? I can see there is a tab in the screen for that estimate which is labelled 'Emails' and I can see a summary of the email sent listed there, but I cannot

• Can't View Project Names in Mobile App

  I can't view project names on PO's in the app, nor can I add that as a viewable PDF field in inventory on the computer. I've attached screenshots showing that in the mobile version whether you are on the PO, editing the PO, or viewing the PO line items,

• Looking for other Zoho users in Canada

  I would like to find other users in Canada to share ideas and suggestions. To see if you are experiencing same issues re HST/taxes, banking, etc.

• Zoho Books' 2025 Wrapped

  Before we turn the page to a new year, it’s time to revisit the updates that made financial management simpler and more intuitive. This annual roundup brings together the most impactful features and enhancements we delivered in 2025, offering a clear

• Intergrating multi location Square account with Zoho Books

  Hi, I have one Square account but has multiple locations. I would like to integrate that account and show aggregated sales in zoho books. How can I do that? thanks.

• Columns with no data still displayed despite "Show missing values" disabled

  I have a table with missing data, but columns are still being displayed even though the "Show missing values" option is disabled. The table contains 3 columns split across 12 months. I suspect the issue is caused by one of the columns using an aggregation

• What's New in Zoho Inventory | January - March 2026

  Hello users, The first quarter of 2026 has been dynamic! We’ve shipped a powerful set of updates in Zoho Inventory to enhance item control, improve warehouse efficiency, expand integration and reporting capabilities. From a unified item creation experience

• Business Day Logic Update: More Accurate Scheduling for Your Workflows

  Hello everyone, We’re improving how business-day calculations work in workflows, especially when triggers happen on weekends. This update ensures that offsets like +0, +1, and +2 business days behave exactly as intended, giving you clearer and more predictable

• Permission Denied - Reports Module - Super Admin

  "Permission Denied Sorry, you cannot view this report because you do not have permission to access one or more of its modules. To view the report, please provide permission to access those modules in the Profiles and Organize Tabs settings." Fresh new

• Allocating inventory to specific SO's

  Is there a way that allocate inventory to a specific sales order? For example, let's say we have 90 items in stock. Customer 1 orders 100 items. This allocates all 90 items to their order, and they have a back order for the remaining 10 items which could

• Changing naming convention for Estimates

  Hi there, How do I customise the naming of the filenames for estimates when sending them? Currently they are named literally just ES11.PDF or whatever the number of the estimate is. There is no Company name, description of the work, customer name, date

• Please design a better spam filter

  Hi Team, While I love Zoho Mail for all the awesome features you have designed - this is the one you need to do a lot of work on - Spam Filter. Your spam categorization seems to be very inefficient - any email containing brand images or a tracking pixel

• Change Default Currency in Zoho Reports

  Is it possible to default all currency fields in my Reports and Tables to my local currency without having to reformat them every time?

• Zoho Project - Total Forecasted Hours

  Does anyone know an easy way to get a total of all the forecasted hours across the portfolio? I'm aware trying to create a custom report that can generate this figure for each task and the total up but the completion percentage doesn't seem to come back

• All new Address Field in Zoho CRM: maintain structured and accurate address inputs

  Availability Update: 29 September 2025: It's currently available for all new sign-ups and for existing Zoho CRM orgs which are in the Professional edition exclusively for IN DC users. 2 March 2026: Available to users in all DCs except US and EU DC. 24

• Zoho Books recurring invoicing link to a Zoho CRM Deal?

  With the Zoho CRM Finance Integration setup, normally when creating an invoice via Zoho CRM Finance Integration on a Deal, it creates the invoice in Zoho Books with the CRM Deal *Potential link for that invoice. Alternatively, if you create the invoice

• Editing Estimates

  Hi team, How do I delete line items in an estimate when editing it? I can't see any option to do this - no X, no trashcan, no drop down... And how do I revert to the original estimate after cloning? I cloned to see if the option to edit were disabled

• Drop Down Menu - Adding up values

  I have a form that has 22 drop down fields each having a value of 0-10 to choose from. Is it possible to have it add up the total value of those selected numbers and have it tally it up in another field at the end? So example: if each of the 22 fields

• Stage-probability mapping feature in custom module

  Hi, I'm building a custom module for manage projects. I would like to implement the stage-probability feature that Potentials has. Is this possible?

• Cross Module Fields Merging between Zoho Sign and Zoho CRM for custom module

  Hello everyone, I've been exploring custom integration between Zoho Sign and Zoho CRM, and I've encountered some interesting findings and would need advanced help. To integrate Zoho Sign with Zoho CRM, there are two primary methods: Installing the extension

• Next Page