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

• Purchase Orders not in sequence

  I am unable to sort by Purchase Order Numbers. I can only sort by date; however, the PO numbers aren't in the order they were entered. This was not the case prior to today.

• Internal Fillable Contract with Zoho Writer (Before Sending to Client)

  Hi everyone, I’m trying to automate the following process in Zoho CRM and would appreciate some guidance. Process: When a Deal moves to a specific stage, CRM triggers an automation. CRM sends a contract template to an internal team member so they can

• Date/time displayed in ZohoCRM does not match date/time of entries in ZohoForm

  Hello there, we use a ZohoForm as a worksheet, i.e. users use it to track start time, break and stop time for every working day. The ZohoCRM org time zone is set on GM -4, so is the Time Zone in the Date&Time section in ZohoForm (see attachment). Despite

• Update Existing Records greyed out in Free Version

  Trying to update records from an Excel sheet, and not getting the option to update. Only option is to add as new accounts. All documentation I can see says update should be an option! Accounts, Leads, Contacts, all the same.

• Dynamically Populate Picklist Values from Another Module Using Client Script

  I am working in Zoho CRM and trying to dynamically populate a picklist field in the Partners module using values stored in another custom module. I have two modules: 1. Partners Module Field: Partner_Type_Pick Field Type: Picklist 2. Partners_Type Module

• Add zoho calendar to google calendar

  Hi I keep seeing instructions on how to sync Zoho CRM calendar with google calendar but no instructions on how to view Zoho calendar in my google calendar.

• Zoho Community Digest : Jan 2026 | Part 1

  Hello Everyone! Staying in the loop with Zoho's latest product updates and features across the vast Zoho Community Forums can be a real challenge. We get it. With over 50+ applications, each with its dedicated forum, it's easy to miss out on important

• World date & time format

  Hello, Is there a timeline to get the worldwide used date and time format ? I mean not the american one... I mean day month year, and 24 hours clock. Regards

• Nimble enhancements to WhatsApp for Business integration in Zoho CRM: Enjoy context and clarity in business messaging

  Dear Customers, We hope you're well! WhatsApp for business is a renowned business messaging platform that takes your business closer to your customers; it gives your business the power of personalized outreach. Using the WhatsApp for Business integration

• Conditional layouts - support for multi-select picklists

  Hi, The documentation for conditional layouts says the following: "Layout Rules cannot be used on the following field types: Auto Number Lookup Multi Select Lookup User Lookup Formula File Upload Multi Line" I have a custom module with a multi-pick list

• 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'. 

• Actual vs Minimum

  Hi all, I am sure I am not the only one having this need. We are implementing billing on a 30-minute increment, with a minimum of 30 minutes per ticket. My question is, is there a way to create a formula or function to track both the minimum bill vs the

• Client Script Not Working When Field is Set by Workflow

  Problem Context: I have implemented a client script in the Cases module that automatically assigns commands based on the value of the Priority field. The script functions correctly when the Priority field is manually set by a user through the form. Observed

• Integration of CRM and Recruit

  hi team, Is it possible to sync deals <> job openings from only 1 pipeline? My configuration of CRM has pipeline for each business unit, so I will have all data in the CRM system. body leasing and recruitment is one BU (hence 1 pipeline) - can I sync

• {Action Required} Re-authenticate your Google Accounts to Continue Data Sync

  Hello Users! To align with Google’s latest updates on how apps access files in Google Drive, we’ve enhanced our integration to comply with the updated security and privacy standards, ensuring safer and more reliable access to your data. With this update,

• integrating Zoho CRM vendors with Zoho projects

  In most of our projects we collaborate with our Vendors. Being able to integrate only Accounts and not Vendors from CRM, is a huge limitation for our perspective and needs. We would really love to see this feature in the CRM-Projects integration.

• Zoho Creator Workshops 2026—Europe & UK | Coming to a city near you!

  Hello everyone! We're excited to announce the Zoho Creator Workshop Series 2026, coming to cities across Europe and the United Kingdom this year! Whether you're looking to explore the intermediate-to-advanced capabilities of Creator or you're a seasoned

• Validation rule for Date field

  The condition settings for a Date field are are absolutlly usless. Conditions can only be set for a specific date, which is logically ineffective in most cases. When setting a condition for a Date field, users usually need to compare the value relative

• Number 9 envelopes for invoice printing

  I email and print invoices. Being new to Zoho and coming from QB, we did both as we have a more traditional So in Zoho i want to do the same using Number 9 envelopes. These have both a return window and mail to windoow see attached image. Im just looking for best suggestions on how to get a ZOHO invoice to work, so I can mail my invoices...

• Zoho Books/Square integration, using 2 Square 'locations' with new Books 'locations'?

  Hello! I saw some old threads about this but wasn't sure if there were any updates. Is there a way to integrate the Square locations feature with the Books locations feature? As in, transactions from separate Books locations go to separate Square locations

• Open Sans Font in Zoho Books is not Open Sans.

  Font choice in customising PDF Templates is very limited, we cannot upload custom fonts, and to make things worse, the font names are not accurate. I selected Open Sans, and thought the system was bugging, but no, Open Sans is not Open Sans. The real

• 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

• Add Reporting feature to display variance/change columns when comparing periods

  When running reports to compare periods (for example, Profit and Loss comparing current year to previous), I would like to be able to display variance columns in both (a) amount or (b) percentage.

• Payroll and BAS ( Australian tax report format )

  Hello , I am evaluating Zoho Books and I find the interface very intuitive and straight forward. My company is currently using Quickbooks Premier the Australian version. Before we can consider moving the service we would need to have the following addressed : 1.Payroll 2.BAS ( business activity statement ) for tax purposes 3.Some form of local backup and possible export of data to a widely accepted format. Regards Codrin Mitin

• Invalid scope choice: Workdrive integration in CRM

  Bug: There is an invalid option in the permission choices for Workdrive integration in CRM. If the entry "WorkDrive.teamfolder.CREATE" is selected, it will return a message indicating invalid OAuth scope scope does not exist.

• What's New - February 2026 | Zoho Backstage

  February 2026 brings a major new addition and a collection of enhancements across Zoho Backstage. We thought about writing a long introduction, but the updates in this release make a strong case on their own. So we’ll skip the buildup and dive straight

• Attaching files to emails within CRM Deals.

  Hello, We have recently started using the extension "Workdrive for CRM" (Related List) to view/store our documents for each Deal, instead of using Attachments. Overall it feels like a better way to go but the user experience is not so great when it comes

• Anyone worked out how to export or screengrab a full heatmap?

  I'd love to be able to include a copy of a heatmap in a report but can't work out how to grab the whole thing as there doesn't appear to be an export function? Thanks in advance.

• Establishing Relationships among contacts/leads with Reciprocal

  Is there any way to create a relationship between contacts and leads and be able to go into just one of the files and have it reciprocate the entry in the other file? For example, if I have two people say John and Jane Smith who are husband and wife.

• Placeholder for Agent Signature in Email Templates

  Dear Zoho Team, I hope this message finds you well. We currently face a limitation when designing email templates in Zoho Desk. While we can create email templates and include a footer at the end, the agent signature is always appended by default at the

• Custom View and Custom Fields on Zoho Books

  Hi, I have some custom fields on Estimates and Invoices. I also use Custom Views so I can have a lot of information at a glance. I want to include my custom fields as columns in my custom views of estimates / invoice, but it looks like is not possible.

• %PaymentLink%

  Does not work. Software creates a BAD link. ....and yes payment options are turned on. Link on the invoice pdf once opened will work but this template is a joke.

• Syncing calendar with Google Calendar doesn't work when events are sent to auto repeat

  Hi... The ZOHO CRM -- GOOGLE CALENDAR sync is broken. If I create a single event on either side, sync works, but if I create an event with auto repeat on either side it doesn't work. Furthermore, events created before the sync don't show up in the calendar.

• Allow Global Admin to access/edit all forms without changing owners

  Hi there, Please consider adding a feature where the Global Admin of the account an automatically access/edit any form in the Company Account. I'm the Global Admin on our Zoho One plan, and we have multiple users that use/create forms. But for me to access

• Can Zoho Marketing Automation send OTP codes via WhatsApp during user registration?

  The flow I would like to implement is: A user signs up in the mobile app and enters their phone number. The system generates a one-time verification code (OTP). The OTP is sent to the user via WhatsApp message. The user enters the code in the app to confirm

• Where to show Customization Field ?

  Dear Sir, I have made some New Field in Item Field Customisation. Now I don't require that field in Estimate, Sales Orders etc. I just wants that field in Sales Invoice to Show/Hide... Is that possible ?

• What's New in Zoho Analytics - February 2026

  Hello Users! We're back with another round of updates for Zoho Analytics. This month's release focuses on giving you greater flexibility in how you visualize, manage, and act on your data - with new features like custom visualizations, remote MCP server,

• Zoho Books (and other Finance Suite Apps) - Clickable Item Name on Invoices and Reports

  Hi Zoho Books team, It would be really helpful if the Item Name on Reports were clicable to take me to the item. The same on Invoices, often I am looking at an invoice and I want to look at the deails of a product. A link here would be helpful to jump

• 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

• Display actual mileage on an invoice

  My users are creating expenses in Zoho expense. For example, they expense 10 miles and get paid 7 dollars (10 miles * IRS rate of .70). If I look at the expenses in Zoho Books, it does show them at 10 miles at .70 cent When I add these expense to an invoice

• Next Page