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

• Kaizen #152 - Client Script Support for the new Canvas Record Forms

  Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved

• Kaizen #142: How to Navigate to Another Page in Zoho CRM using Client Script

  Hello everyone! Welcome back to another exciting Kaizen post. In this post, let us see how you can you navigate to different Pages using Client Script. In this Kaizen post, Need to Navigate to different Pages Client Script ZDKs related to navigation A.

• Kaizen #210 - Answering your Questions | Event Management System using ZDK CLI

  Hello Everyone, Welcome back to yet another post in the Kaizen Series! As you already may know, for the Kaizen #200 milestone, we asked for your feedback and many of you suggested topics for us to discuss. We have been writing on these topics over the

• Recent Topics

• Can I use a Standalone CRM Function as the Callback URL For Async Export Data API?

  I am creating an export job using this API https://www.zoho.com/analytics/api/v2/bulk-api/export-data-async/create-export/view-id.html There is a "callbackUrl" key in the CONFIG object. I tried copying the URL for a standalone function in CRM which can

• Future Orders - Due Date

  Hi In my role, I can receive tickets where the work required is requested months in advance. Using a Future Orders option, which I believe was setup under the On Hold status type, hides the Due Date, in all views/ticket etc. Whilst I understand the reasoning

• Introducing Withdrawal Reasons for Offers

  We’re excited to introduce a new enhancement to the Offer module that brings more clarity and accountability to every withdrawn offer. The Withdrawal Reason update ensures that each withdrawal — manual or automatic — is backed by a clear explanation,

• Zoho Creator customer portal users

  Hi, I'm in a Zoho One subscription with our company. I'm running a project now that involves creating a Zoho Creater application and using the Zoho Creator Customer Portal.  At most we need 25 customer portal users. In our Zoho One plan we only get 3

• GPS tracking only or Check out facility

  Dear Team, Zoho CRM is quite robust CRM but till date i was waiting for the feature of having GPS tracking of Sales employees which is a common demand by all customers for thier field sales executives. We cover them by saying that CRM provides Checkin

• HTML Tags added to Reports with Notes

  Recently Zoho added the ability to markup text within notes. That way, users can change font size, colors, etc. It's a great change. However, since the change, reports that include a column for "Note Content" are printing HTML tags within the report.

• In App Auto Refresh/Update Features

  Hi,    I am trying to use Zoho Creator for Restaurant management. While using the android apps, I reliased the apps would not auto refresh if there is new entries i.e new kitchen order ticket (KOT) from other users.   The apps does received notification but would not auto refresh, users required to refresh the apps manually in order to see the new KOT in the apps.    I am wondering why this features is not implemented? Or is this feature being considered to be implemented in the future? With the

• Appraisals on Employee Information Profile

  Is it possible to show completed appraisals on each employee's "Employee Information" page? I would presume at the bottom - similar to the "Related Lists" concept in Zoho CRM. Obviously view access would be limited to employee and appropriate other roles

• AI Interview Insights: Turn Recorded Interviews into Quick Transcripts & Summaries

  Evaluating interviews shouldn’t require replaying long recordings or taking manual notes. With AI Interview Insights, you can now review complete transcripts and AI-generated summaries of your One-way (Recorded) interviews right inside Zoho Recruit. This

• Customer ticket creation via Microsoft Teams

  Hi all, I'm looking to see if someone could point me in the right direction. I'd love to make it so my customers/ end users can make tickets, see responses and respond within microsoft teams. As Admin and an Agent i've installed the zoho assist app within

• Kaizen #220: Actions API - Webhooks APIs - Part 2

  Hello all!! Welcome back to the follow-up Kaizen post of Kaizen #219: Actions API - Webhooks APIs - Part 1. In the previous week, we covered how to configure a basic Webhook and how to include Headers, Body, and URL Parameters using both the POST Webhook

• Standard Payment Term is not pulled from account to quotation

  Hey Team There seems to be something off. I do have "Net 30" as my default payment term in Zoho Books for my customers. If, from the customer overview or quote section, I create a new Quotation, the payment terms field stays blank and doesn't get the

• Request for Auto PO - Min–Max based Automated Purchase Feature

  Dear Zoho POS Team, I’m writing to request a feature enhancement that would significantly streamline inventory management for businesses using Zoho POS — particularly supermarkets, FMCG retail, and multi-store operations like ours. Feature Requested:

• Canva Integration

  Hello! As many marketing departments are streamlining their teams, many have begun utilizing Canva for all design mockups and approvals prior to its integration into Marketing automation software. While Zoho Social has this integration already accomplished,

• Manage your invoices from Bigin's mobile app (iOS)

  Hello everyone! We're happy to announce that users can now integrate Zoho Books with the latest version of Bigin's iOS app. Zoho Books can be integrated with Bigin only via the web application. Users can view the Zoho Books tab in the detail pages of

• HubSpot CRM to Zoho Creator Integration

  I'm trying to create an integration between HubSpot CRM and Zoho Creator with HubSpot being the push source (if a contact is created or updated in HubSpot, it pushes the information to Zoho Creator). I have two questions: 1- Is it best to use Zoho Flow

• Systematic SPF alignment issues with Zoho subdomains

  Analysis Period: August 19 - September 1, 2025 PROBLEM SUMMARY Multiple Zoho services are causing systematic SPF authentication failures in DMARC reports from major email providers (Google, Microsoft, Zoho). While emails are successfully delivered due

• Accessibility controls and multilingual captcha authorization for Help Center users ​

  Hello everyone, As part of our ongoing effort to improve user experience, we are excited about the accessibility controls and predefined accessibility personas added in the Help Center, similar to what is already available in Zoho Desk. Help Center users

• Gain control over record sharing with portal users through our new enhancement: criteria-based data exposure

  Dear Customers, We hope you're well! Portals is a self-service avenue through which your clients can access and manage their direct and related data in Zoho CRM. This empowers them to be more independent and enables them to experience a sense of transparency

• Ticket Status email

  Good day, This was discussed in the past, but it would be helpful if we could have the system assign a custom response to a status. We have various statuses for tickets, e.g. "closed due to no response", or "Pending Status", it would be helpful for the

• Zoho Sign + Zoho CRM : la solution pour simplifier vos accords de vente

  La conclusion d’un contrat de vente nécessite de nombreuses étapes : préparation de documents, validations successives et collecte des signatures. Les équipes commerciales passent souvent par plusieurs cycles de collaboration et de révision, tout en assurant

• Zoho Desk Limitations

  Good day, all, I would like to know whether others share my frustration with some of Zoho's limitations. Don't get me wrong, I like Desk (and I also have a subscription for Analytics), I have been with them for close to 10 years, and unfortunately, I

• Item/service subtotal

  Just discovered & really pleased that we can drag to re-order the line items in Sales orders & Invoices, a very nice feature which doesn't seem to be documented? It would be nice to be able to insert a subtotal as a line item to complete this great feature

• Converting Sales Order to Purchase Order

  Hi All, Firstly, this code works to convert a sales order(SO) to a purchase order (PO) via a button, however I am running into an issue when I convert the SO where the values from the line items are not pulled across from the SO to the PO. The ones in

• how to Solve Conflict Invoices in Zoho POS

  Hello Team, I am facing a repeated issue in Zoho POS while saving a sale that contains service-based items. My products are intentionally created as Service (Non-Inventory) items because I do not want to track stock for them. However, every time I try

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

  The address field will be available exclusively for IN DC users. We'll keep you updated on the DC-specific rollout soon. It's currently available for all new sign-ups and for existing Zoho CRM orgs which are in the Professional edition. Latest update

• Copy, Paste, Highlighted text

  when i copy paste text it gets highlighted. Fix this.  WTF is with this black highlight ? Fix copy pasting. Some people pay for using this mail service. 

• Pricing Strategies: #6 Common Mistakes while Configuring Pricing

  "Why does this month's billing feel messy again?" That was the exact line Priya muttered while staring at the spreadsheet full of edited pricing, one-off discounts and mismatched subscription details. Her business was growing, but the pricing machine

• Publish to LinkedIn via API

  Hi, Is it possible to publish a job opening to LinkedIn (paid job slots) if creating a job opening via api / deluge function? Or is the user required to manually publish via the job boards process? Many Thanks Adrian

• FSM - Associating and selecting Contacts based on Service Addresses

  Hi FSM team, I've come across an FSM limitation I wanted to share for improvement. I'm currently configuring FSM for a client who provides heating system install and maintenance services. The are often sub contracted by building management companies to

• 日本語フォントの選択肢拡充についての要望

  日本語フォントの選択肢がとても少ないと感じたことはありませんか？ 多くのアプリ（たとえば Invoice）ではフォントが1種類しかなく、正直あまり使いやすい・見た目が良いとも言えません。 そろそろ、もっと多くの日本語フォントを追加してほしい、そしてすべてのアプリで同じフォント選択肢を使えるようにしてほしいと、私たちユーザーが声を上げる時期だと思います。 ご存じのとおり、現状ではアプリごとにフォント周りの仕様にほとんど一貫性がありません。 みなさん、一緒に要望を出していきましょう！

• Do Unpublished Products in Shopify Sync to Zoho POS?

  Will an unpublished product in Shopify sync to Zoho POS? I would like to know how Zoho POS handles products that are in draft/unpublished status in Shopify.

• Problem in Zoho POS frontend ERP.

  We are facing some difficulties in our billing and inventory processes and require your support to resolve them at the earliest. Customer Advance Payments We receive advance payments from customers for upcoming sales. Please guide us on how to record

• How to create estimates/Invoices with sub-totals

  Every other accounting package can create estimates and invoices with Sub-totals. How can I do that in ZohoBooks?

• Categorize Items with Item Headers

  Hello customers, Did you ever want to classify items based on specific categories to help your customers understand your invoice better? With the new Item Header feature, you can easily categorize items in your invoices and estimates and give them a common title.  Item Headers are available in the Invoices, the Recurring Invoices and the Estimates module. It can be carried forward from estimates to invoices at the time of converting the estimates.  To add an item header: Go to the Estimates, Invoices

• Emails sent through Bigin are not posting in IMAP Sent folder

  I have set up my email to work from within Bigin using IMAP.  I am using IMAP so I can sync my email across multiple devices - phone / laptop / desktop / iPad / etc.  I want all my emails to populate my email client (outlook & iphone email) whether or

• Ask the Experts 26: Brighten every customer interaction with Zoho Desk all year long

  Hello everyone, Greetings and welcome to Ask the Experts 26. As we wrap up 2025, we are excited to invite you to the 26th episode of our Ask the Expert series. 🎄The Merry Metrics Edition = Best of Zoho Desk [Best Practices + Holiday Automation + Year-End

• Painfully Slow Zoho mail

  Since yesterday Zoho Mail seems to have starting functioning very slowly and having a few bugs. It's slow to open mails, slow to send, slow to change between email accounts. Sometimes clicking on a particular folder (eg Sent folder) stops working and

• Discount on the transaction level in POS

  "Is it possible to apply a discount on the total bill before tax in Zoho POS?" I want to apply a discount on the total transaction amount in Zoho POS, but the discount should be calculated before the taxes are applied. Is there an option to do this in

• Zoho DataPrep switching Date Format

  When using a pipeline that is importing Zoho Analytics data into Zoho DataPrep, the month and day of date fields are switched for some columns. For example, a Zoho Analytics record of "Nov. 8, 2025" will appear in Zoho DataPrep as "2025/08/11" in "yyyy/MM/dd"

• Next Page