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

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!

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








      • 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

        • Unable to Delete Items – No Visible Transactions but Error “Items which are a part of other transactions cannot be deleted…”

          Hello Community, We are using Zoho Inventory for our business and encountered a persistent issue that is preventing us from deleting certain items. The message shown is: “Items which are a part of other transactions cannot be deleted. Instead, mark them

        • Keyboard UX for Assemblies

          The new Assembly module has a counter-intuitive behavior that ought to be corrected. When an Assembly is ready to be entered, there are two options given, the blue-highlighted "Assemble" and the gray "Save as Draft". This correctly implies that the normal

        • landed cost-need help with different currency under the same bill

          I’m having trouble recording landed costs in Zoho Inventory/Books. My purchase order is in CNY, but the landed cost (freight) I pay is in USD. Zoho forces everything under the same bill to use one currency, so I can’t enter the landed cost in its actual

        • Improved Functionality PO Bill SO Invoice

          Hello, I need to enter over 100 items, it's frustrating to scroll a few item rows and wait for more to load, then scroll again. It would be nice to have buttons that scroll to the top or bottom with one click. Furthermore, these items I'm adding are VAT

        • Generate a link for Zoho Sign we can copy and use in a separate email

          Please consider adding functionality that would all a user to copy a reminder link so that we can include it in a personalized email instead of sending a Zoho reminder. Or, allow us to customize the reminder email. Use Case: We have clients we need to

        • I would like to request a new feature or setting for SalesIQ.

          Hello Zoho Team, I would like to request a new feature or setting for SalesIQ. Currently, when a user opens our contact widget and clicks on the "Chat with us" option, it opens a standard chat window that remains empty until either the user types a message

        • In Zoho inventory Converting sales return to cerdit note from using Api from Creator Error details: {"code":-1,"message":"Invalid Sales Return ID."}

          In Zoho inventory Converting sales return to cerdit note from using Api from Creator Error details: {"code":-1,"message":"Invalid Sales Return ID."} this is button Function used in the Creator map Inventory.Create_Credit_note(int CRE_ID) { return_value

        • Realtime Translations of Video via OnAir

          It would be an amazing feature to have a drop down selector in the On Air video area for attendees to select a language to convert the original language to.

        • Zia should track how customer relationships evolve over time

          Here's a feature idea that I've been thinking about The Problem Zia is great at analyzing individual interactions email sentiment, call transcription, best time to contact. But here's what it can't do: tell you how a relationship has evolved over time.

        • First Name in Mail

          While sending a mail/message to the user, I want only the first name to be displayed—for example: “Hi John” instead of the full name using "Hi ${Name_Field}"

        • Looking for Guidance on Building a Zoho Website

          I'm exploring the possibility of building a custom website with specific features using Zoho as an alternative platform. My goal is to create something similar to https://gtasandresapk.com , with the same kind of functionality and user experience. I'd

        • FSM integration with Books

          Hi, I have spent a few months working with FSM and have come across a critical gap in the functionality, which I find almost shocking....either that, or I am an idiot. The lack of bi-directional sync between Books and FSM on Sales Orders/ Work Orders

        • How to Track Inventory Usage from Zoho FSM to Zoho Inventory?

          Hi everyone, We’re currently working on integrating Zoho FSM with Zoho Inventory, and we’ve encountered a challenge we’re hoping the community can help us understand better. Here’s the context: When we create a Work Order in Zoho FSM that involves parts

        • Set Field Mandatory by Client Script ZOHO CRM

          #Tips of the day We can set the field as mandatory by the client script var field_obj = ZDK.Page.getField('Custom_Field1'); field_obj.setMandatory(true); Custom_Field1 = Field API Name Apart from is if you have required any kind of Zoho work please do

        • associating products with accounts

          I have all my accounts and products in zoho now. I need to generate a sales order for an account. The product lookup feature on the sales order shows no products...how can I get them to appear.

        • Can we rely on order of returned ids when inserting multiple records?

          Hello! API https://www.zoho.com/crm/developer/docs/api/v8/insert-records.html does not mention that the response array will match the input array*, keeping this important information implicit and someone might have doubts to rely on it. (*the response

        • New UI for Writer - Disappointed

          I've been enjoying Zoho Writer as a new user for about 6 months, and I really like it. One of my favorite things about it is the menu bar, which you can hide or leave out while still seeing most of your page because it is off to the left. I think this

        • Zoho CRM Community Digest - February 2026 | Part 2

          In this edition, we’re highlighting a few more product enhancements, along with some helpful community discussions that explore everyday CRM scenarios from automating reminders and managing lead outreach to making the most of APIs and client scripts.

        • Dont want to list inactive items.

          If an item is made inactive, there is no point in showing it in the item list. Please provide an option to hide all inactive items in 'Preferences'. 

        • Client Script event on any field of a Detail page

          Hi everyone! I'd like to trigger a Client Script when a user modifies a field - any field - from the Account Details page, how can I do this? I don't want to trigger it on a specific field, but on all of them. Thanks in advance!

        • Tip #66 - Exploring Technician Console: Network Statistics - 'Insider Insights'

          Hello Zoho Assist Community! Have you ever wondered why a remote session feels sluggish, or wanted to check whether connectivity issues are on your end or the customer's? That's exactly where the Network Statistics feature in Zoho Assist comes to the

        • Syncing zoho books into zoho crm

          I was wondering how I can use zoho books in crm as I have been using them separately and would like to sync the two. Is this possible and if so, how? Thanks

        • REFUND REQUEST FOR PLAN SUBSCRIPTION CANCELLED

          I have cancelled my Zoho Books subscription and would like to request a full refund for the subscription. Kindly process the refund at your earliest convenience.

        • purchasing a pagkage

          goodmorning i want to pay for my monthly package but your app is sayinng i have insufficient funds yet i loaded money on my account yesterday though in our currency of ugx

        • Edit Receipt, how?

          Do you notice the big blank space in Receipt? I want to remove that. I know there is a template but that blank space, I can't seem to remove it. Please help. Thank you!

        • Can I export a TXF (TurboTax exchange format) file out of Zoho Books?

          Hello, I'm trying to do my US Small Business Taxes using Intuit's Turbo Tax. Can I export my expenses from Zoho Books to a TXF format file, so that it can then be imported into Turbo Tax? Thanks, Rajnesh

        • Tax inclusive and exclusive for Sales invoices

          Hello, where can I set my tax to be inclusive or exclusive for invoices in Zoho Books? There used to be a button for me to do that right above the products table. Can someone help me please? Thank you!

        • Unable to produce monthly P&L reports for previous years

          My company just migrated to Books this year. We have 5+ years financial data and need to generate a monthly P&L for 2019 and a monthly P&L YTD for 2020. The latter is easy, but I'm VERY surprised to learn that default reports in Zoho Books cannot create

        • ZOHO Reports are taking longer time to get refresh

          Hi Team, Since last few days, I'm facing issues in getting updated reports. For eg: right after making an expense entry or even posting a journal, it is taking longer then expected for the updated reports. Refer below: "You are viewing the report that

        • audio and video comments in tasks in zoho projects

          Hi, is it planned to have the ability to post audio and video comments? the whatsapp wechat format of communicating is a reality... tools like zoho project would facilitate a lot teamwork by facilitating the way in which we can give feedback in audio and video rather than only text. thx!

        • Looking for Zoho + Twilio Automation Specialist (Duda Website Integration)

          Hi everyone, I’m looking for an experienced Zoho specialist to help build a mostly automated CRM and booking system for my service business. I already have a live website built on Duda.co and need help integrating my existing forms into Zoho CRM (no rebuild

        • Zoho CRM For Everyone UI Rollout Begins for All Users

          Hello Partners, We have started rolling out the new Zoho CRM For Everyone UI as the default experience for all users. This update is being released in three phases based on organization size and account type. We want to keep you informed of the rollout

        • How to retreive the "To be received" value of an Item displayed in Zoho inventory.

          Hi everyone, We have our own Deluge code to generate a PO according to taget quantity and box quantity, pretty usefull and powerful! However, we want to reduce our quantity to order according to "To be received" variable. Seems like this might not even

        • Introducing Explainer Videos for Zoho Desk: Solve everyday challenges with simple configurations

          Dear everyone, We have created a set of short explainer videos that show how common support scenarios can be handled using simple configurations within the product. The solutions often lie in the plain sight, but go unnoticed. Through these videos we

        • Notifications Feeds unread count?

          How do I reset the unread count on feeds notifications?  I've opened every notification in the list.  And the count never goes to zero.

        • Simple reliable solution to convert MSG files for AOL Mail?

          A simple and reliable way to convert MSG files for AOL Mail is by using a professional tool MacGater Mac MSG Converter. This software allows users to quickly convert MSG files into formats compatible with AOL, such as MBOX or direct email migration. It

        • Zoho One Support is non existent...

          I've tried through Email, Chat, this community and finally through Phone. There is no way to receive an answer. Email = over a week and no answer Chat = not available Community = no answer at all Telephone = after clicking myself through the callcenter

        • Disable Zoho Contacts

          We don't want to use this app... How can we disable it?

        • Custom module - change from autonumber to name

          I fear I know the answer to this already, but thought I'd ask the question. I created a custom module and instead of having a name as being the primary field, I changed it to an auto-number. I didn't realise that all searches would only show this reference.

        • Edit a previous reconciliation

          I realized that during my March bank reconciliation, I chose the wrong check to reconcile (they were for the same amount on the same date, I just chose the wrong check to reconcile). So now, the incorrect check is showing as un-reconciled. Is there any way I can edit a previous reconciliation (this is 7 months ago) so I can adjust the check that was reconciled? The amounts are exactly the same and it won't change my ending balance.

        • Next Page