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

• Extend GitHub Commit Integration to Tasks in Zoho Projects

  Hello Zoho Projects Team, We hope you are doing well. We would like to submit a feature request regarding the current GitHub integration in Zoho Projects, specifically the ability to link commit information. Current Limitation: As of now, Zoho Projects

• Add Native GitHub Pull Request Creation & Management from Tasks/Bugs

  Hi Zoho Projects Team, I am submitting a feature request to enhance our development lifecycle by enabling native GitHub Pull Request (PR) creation and management directly within Zoho Projects. The Current Limitation: Currently, the GitHub integration

• Add Actionable “Smart Commits” for GitHub Integration

  Hi Zoho Projects Team, I am submitting a feature request to introduce Smart Commits support for the GitHub integration in Zoho Projects. The Current Limitation: Currently, Zoho Projects offers a "passive" integration. Including a Task ID in a commit message

• Add Unified Project-Wide Development & Release GitHub Dashboard

  Hi Zoho Projects Team, I am writing to submit a feature request for a Unified Development & Release GitHub Dashboard that provides centralized GitHub visibility at both the Project and Milestone levels. The Vision: We need a single "Command Center" that

• Add Native “Create GitHub Branch” Action for Tasks and Bugs

  Hi Zoho Projects Team, I would like to submit a feature request to enhance the GitHub integration in Zoho Projects by adding the ability to initiate a GitHub branch directly from a Task or Bug. The Current Limitation: Currently, Zoho Projects lacks a

• One-click “Open in VS Code” from Zoho Tasks/Bugs with automatic branch checkout

  Hi Zoho Projects Team, I am submitting a feature request to enhance the development workflow within Zoho Projects, specifically the ability to open a Task or Bug directly in VS Code and automatically check out the related branch, similar to capabilities

• How to reduce inventory valuation when not tracking individual items?

  We purchase clothing items wholesale, embroider them with a company's logo, then resell. The garment style, size, color, etc. changes according to a customer's desire, so we don't track the individual item's purchase within Zoho Inventory unless there's

• Merge tag didn't work in the campaign sent to test email list

  Hello, I just sent out a campaign to my list of test emails (including my personal one). The merge tag that's supposed to put a first name of the contact $[UD:FIRST_NAME||]$ didn't work. Where the first name of the contact should be displayed there's

• Add Camera Background Blur During Recording

  Hi Zoho WorkDrive Team, Hope everything is well. We would like to request an enhancement to the video recording feature in Zoho WorkDrive. Currently, the camera preview displayed during a recording does not support background blur. This is an essential

• Sync Data from MA to CRM

  Currently, it's a one-way sync of data from the CRM to MA. I believe we should have the ability to select fields to sync from MA to the CRM. The lead score is a perfect example of this. In an ideal world we would be able to impact the lead score of a

• How can I transfer data from Production to Development environment?

  Hi, I am using Creator V6 and would like to bring all the data in production to the Development and Testing environments? Is there an easy way of doing that or I have to export and import each table?

• filter on sheets mobile (iOS, iPadOS) does not work

  re-posting this as a question because reporting as a problem netted zero responses... I have this issue on every spreadsheet, whether imported or created natively in Zoho Sheets. I can use on desktop without issue: but on iOS the filter dropdowns are

• How to map fields from Zoho Recruit to Zoho People

  I've got these fields from my Job Offer that I'm trying to map to the Work information fields in Zoho People, but they arent showing up. For example, how do I get the department name field (in the job post) to map to the work information field in Zoho

• Mass email from Report output

  Hi, I'd like to send a mass email based on a report output. The report is pulling multiple information from linked modules. Each line of the report ends up with a contact name, email and multiple field values pulled from the linked modules (some are custom

• 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

• Add Comprehensive Accessibility Features to Zoho Writer

  Hello Zoho Writer Team, We hope you are doing well. We would like to submit a feature request to enhance Zoho Writer with a full set of accessibility tools, similar to the accessibility options already available in the Zoho Desk agent interface. 🚧 Current

• How to see Tickets that require a response

  When an agent checks his work he should be able to see a list of tickets that he has to reply to. Currently he can only see if the ticket is closed or open. However the ticket might be open but we are waiting for the customers reply, so there is nothing

• 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

• [Free webinar] Integrations in Zoho Creator - Creator Tech Connect

  Hello everyone, We’re excited to invite you to another edition of the Creator Tech Connect webinar. About Creator Tech Connect The Creator Tech Connect series is a free monthly webinar featuring in-depth technical sessions designed for developers, administrators,

• Issue with attaching files to a task through the API

  Hello! I've implemented a function that creates a task for every new bill that is created but I haven't been able to attach to the task the files which are attached to the bill. I have encountered multiple errors but the most common one is error 33003:

• 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

• Can I hide empty Contact fields from view?

  Some contacts have a lot of empty fields, others are mostly filled. Is there a way I can hide/show empty fields without changing the actual Layout? I would like to de-clutter my view, and also be able to add information later as I am able. I would be

• Agents permission per department

  Hi Team, can I setup permission for each agent what they can do in each department, for example I want account department agents to only have view access to support department tickets and not allowed to assign or reply to clients. I am sure this would

• Ask the Experts - Live Q&A webinar

  Hello Community, We’re excited to host our very first Ask the Experts session! Join us on 7 April 2026 from 11 a.m. to 12 p.m. (IST) for this live webinar Q&A session, where you will have an opportunity to connect directly with our product experts, gain

• 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

• Prevent Automatic Milestone Inheritance for Newly Created Task Lists

  Hello Zoho Projects Team, We hope you are doing well. We would like to request an enhancement regarding how new task lists inherit Milestone association in Zoho Projects. Current Behavior: At the moment, when a new task list is created below an existing

• Hiding / removing Currency field from Layout

  Hello, I'm working on the LEAD standard layout of Zoho CRM. I like to have it as minimal as possible for our team. I could remove most of the field, but Currency is not possible. As lead, I don't quite understansd the necessity to have Currency as mandatory.

• Updating Sales orders on hold

  Surely updating irrelevant fields such as shipping date should be allowed when sales orders are awaiting back orders? Maybe the PO is going to be late arriving so we have to change the shipment date of the Sales order ! Not even allowed through the api - {"code":36014,"message":"Sales orders that have been shipped or on hold cannot be updated."}

• Can we have Backorder Management ?

  Can we have Backorder Management ?

• Accept credit card payment for multiple invoices

  We have a problem with Zoho Books.  While we can charge a customer's credit card for an individual customer invoice, we cannot charge a customer's credit card for more than one invoice. In our business, it is common for a client to phone up and say, "Here

• Anyone in Australia using Zoho Books AND has their account with NAB?

  Hi I have an account with both NAB and Suncorp. Suncorp transaction come in the next day however NAB transactions take 4-5 business days to appear. eg: A deposit made today in my Suncorp will be imported into Zoho tomorrow. A deposit made today to the NAB account will be imported maybe Saturday (Friday overnight). I have contacted both Zoho and NAB but noone seems to know why. I was just wondering if anyone else in Australia uses NAB and has this issue (or doesn't) maybe we could compare notes and

• Newby Questions - Vendors, Customers, and Income vs. Other Income Clarifications

  Q1. For Deposits, there does not seem to be an option for "Income". "Other Income" is an option however. What is the process to add the option to assign a deposit to type "Income"? Q2. In many cases Vendors and Customer are the same. Vendors may purchase

• ISO 3166-2 Compliant Country and Regions

  Zoho should consider implementing ISO 3166-2 standards for countries and regions in address dropdowns. It adds a lot of noise in the data when items added programmatically conform to ISO 3166-2 (e.g., TX for Texas, CA for Canada, etc.), but the few items

• Tax on Imported goods charged by Shipping Company

  Hi Folks, I imported goods from outside Canada, for better understanding I will give an example data. imported goods value: 2000$ The shipping company sent me an invoice containing the following information: Custom duty on imported goods: 400$ Administration

• Invoice Import Error: "Either Tax or Tax Exemption Reason is required" - Recurring Across All Attempts

  Issue Description: I'm experiencing a critical issue with invoice imports in Zoho Books. Every import attempt fails with the same error message, regardless of the tax data provided: Either Tax or Tax Exemption Reason is required. This error is blocking

• Zia Agents in Zoho CRM: a better way to set up digital employees

  Hello everyone, If you've been using Zia Agents in Zoho CRM, so far using Connections was the only deployment method you're familiar with. You create an agent in Zia Agents (define its objective, write instructions, use tools, add knowledge base) and

• Amazon FBA integration - Handle invoice reconciliation under different GSTINs,

  Dear Zoho Community, Thank you for the clarification regarding the Amazon FBA integration, default warehouse, and GSTIN mapping in Zoho Inventory. I understand that Zoho currently supports only one warehouse for Amazon FBA, and that all FBA orders are

• Zoho CRM Copilot Connector

  Hello, Are there plans to release a connector for Zoho CRM and Copilot? I'm in the early research stages of potentially switching our CRM solution to Microsoft Dynamics because of its out of the box integration with Copilot. The advantage being that we

• Zoho Sheet for Desktop

  Does Zoho plans to develop a Desktop version of Sheet that installs on the computer like was done with Writer?

• Automation Series: Notify Admin When User Accepts an Invitation

  In Zoho Projects, a portal is an organisational-level workspace where user can manage multiple projects. To join a portal, a user will have to accept the portal invitation. However, it is important for admins to be in the loop when a user accepts the

• Next Page