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.









        • Recent Topics

        • How to Add Time Formula Duration (hh:mm)

          Hi everyone — I’m trying to create a formula field in Zoho CRM that calculates the difference between a “Call Start Time” and “Call End Time” and displays the duration in HH:MM format (for example: 1:04 for one hour and four minutes). My current setup

        • How can I calculate the physical stock available for sale?

          Hey Zoho Team,  I've tried to calculate the physical stock on hand in various ways - but always receive a mismatch between what's displayed in Zoho Inventory & analytics.  Can you please let me know how the physical stock available for sale is calculated?

        • Set Custom Icon for Custom Modules in new Zoho CRM UI

        • Live Webinar: Getting Started with Zoho WorkDrive - A Complete Overview

          Hello everyone, We’re excited to invite you to our upcoming live webinar! Discover how to set up your team, bring in your data, and make the most of WorkDrive’s collaboration, organization, AI, and security capabilities. This session is perfect for anyone

        • Marketing Tip #4: Build your email list early

          Email marketing has one of the highest returns on investment. Don’t wait until later; start collecting subscribers now. When you've got their attention, you can send them emails about offers, new product launches, seasonal greetings, and more. Try this

        • Is anyone else having trouble saving a custom image in their email signature, or is it just me?

          When I try to save the image I get an error that says "Operation Failed" I opened a support ticket two weeks ago and received a response that it would be debugged, but it still isn’t working

        • Unify Overlapping Functionalities Across Zoho Products

          Hi Zoho One Team, We would like to raise a concern about the current overlap of core functionalities across various Zoho applications. While Zoho offers a rich suite of tools, many applications include similar or identical features—such as shift management,

        • Zoho Desk Domain mapping / Cloudflare CNAME not recognized

          Hello, my website is behind Cloudflare and SSL. From the Cloudflare control panel I added a CNAME record such as support.mydomain.com pointing to desk.cs.zohohost.com but I'm stuck with the message "Make sure you've mapped the CNAME entry..."

        • Power of Automation :: Quick way to associate your Projects with Zoho CRM

          A custom function is a software code that can be used to automate a process and this allows you to automate a notification, call a webhook, or perform logic immediately after a workflow rule is triggered. This feature helps to automate complex tasks and

        • Create an Eye-Catching Announcement Widget for Your Help Center

          Hello Everyone! In this week’s edition, let’s explore how to keep your customers updated with exciting news in the Help Center. See how ZylkerMobile wowed their customers by bringing updates right to their portal. ZylkerMobile, the renowned brand for

        • I want to add my other zoho account in same pc

          why does zoho restrict me doing many things as i also want to add my second mail account bit its not allowing me to do that

        • Search in Zoho Community Not Working

          I realize this is a bit of a meta topic, but the search for the various Zoho Communities appears to not be working. I'm under the impression that they run on some version of the Zoho Desk platform, so I'm posting this here.

        • Capture Stripe’s Customer ID

          Does anyone know of a way to capture Stripe’s customer ID that is created when the form/payment is processed? I would like to have the customer ID stored in our CRM so we could utilize in some custom functions down the road.

        • Custom Modules - Where are Comments??

          In the standard ticket module and in the tasks module, we have an interactive comment box that we can post important details/notes and can tag others if needed. Where is this functionality for Custom Modules? Ideally, custom modules would have very similar,

        • Dynamic Signature - Record owner

          Hi everyone, I’m using Zoho Writer merge templates from Zoho CRM and have two questions: Owner signature: How can I automatically insert the CRM record owner’s signature in the merged document? I’m not sure where this signature is stored or how to reference

        • PUNJAB NATIONAL BANK (CORPORATE) INDIA - NOT AVAILABLE IN BANKING

          Dear sir, Kindly fix it. PUNJAB NATIONAL BANK (INDIA) is available but PUNJAB NATIONAL BANK (CORPORATE) is not available. Kindly enable this banking since we need to categorize the entries. Regards, Sanjay Jena email id/ user id : travewithmerchant@

        • Amazon invoice in Zoho Books

          I have just made my first few sales on Amazon India. Amazon Seller account generates invoices for the sales made on Amazon. These invoices are sent to customers also. Now when I was only making offline sales, I used to create Invoices in Zoho Book. Now

        • CUSTOM FUNCTION GIVE ERROR #EVAL!

          CUSTEM FUNCTION CREATE KYA ZOHOSHEET ME US FUNCTION KO USE KIYA LEKIN DATA TO SAHI HAI LAKIN DATA SHEET ME NAHI LAG LAHA HAI KRUPYA SOLVE KARE MY CODE IS float ADDTWO_TWO(float NO1, float NO2) { ADD = NO1 + NO2; return ADD; }

        • Zoho ShowTime: Certificates of Completion - Award your learners with a sense of achievement

          In our increasingly competitive market, professional trainers need to differentiate themselves if they are to survive. One way to do this is to focus on innovation and deliver an ideal learning experience. By developing a renowned certificate program that provides learners with a specialized skill set for a particular industry, both trainees and future prospects will recognize the trainer's leadership in that field. This can help with long-term growth, revenue generation, and even marketing and branding.

        • IMAP Migration from Gmail

          I have been trying to import my email from a Gmail server and keep receiving the following error. I have reduced the security, activated imap and no improvement. The link to the Google support item has not helped. Unable to connect to your account. Please

        • Your Incoming has been blocked and the emails will not be fetched in your Zoho account and POP Accounts Click here to get unblocked.

          When entering my account, this error is thrown at me, and I deleted a good part of my deleted messages, but I still can not unblock it, I would appreciate your help. reservas@lineasperutravel.com

        • Request for Creating Multiple Email Accounts on One Mobile Number

          Dear Zoho Team, I am planning to shift all my work-related communication to Zoho Mail because of its reliability and features. For my work, I need to create 3–4 separate email accounts for different purposes. Could you please confirm if it is possible

        • Signature issue

          Problem: The signature does not appear when replying or forwarding an email. solve issue: settintgs/Signature Check option place a signature above the content with quotation marks

        • mail admin not loading

          i am trying to login to mailadmin ... gears keeps rotating forever... its not a password issue whats so ever ... not cookies issues whatsoever from android app i can login but there so few things to do from there .. i changed ip address the same... i

        • Unify All Zoho Video Meeting Experiences into One Standardized Platform

          Hi Zoho Team, We would like to share an important user experience concern regarding the current state of video meeting functionality across the Zoho ecosystem. The Problem Within Zoho, there are multiple ways to initiate or schedule a video meeting: Zoho

        • Changing Account in Quote form does not update address information.

          I am trying to update the address information in a quote I've created. I corrected the address in the "Account" but that did not change in the quote. If I re-enter the Account Name in the Quote form, nothing updates. How do I fix this?

        • Zoho One Backup of entire account

          Hello, When using Zoho one is there a way to backup your entire account of all apps that you are using \ activively using in a single step or do you have to backup each applications data individually? Thanks,

        • ZIA in Zoho Cliq

          Is It possible to use the ZIA feature from Zoho Analytics in the Zoho Cliq?

        • Issue with “CC” and “Subject Details” of the initial mail when reply / replied all / forward using Zoho Mail Client (Desktop / Web Mail / Mobile App)

          It is observed that when I reply / reply all / forward a mail using Zoho Mail Client (Desktop / Web Mail / Mobile App), the “CC” and “Subject Details” are omitted from the mail which was replied/forwarded. However this is not the case with outlook mail

        • Unable to send Emails - 452 4.3.1 Temporary System Error

          Whene ever i request smtp server to send the email (without attachment). i recieve error "452 4.3.1 Temporary System Error"

        • I can't receive email

          I cannot receive any email sent to my Zoho email after the free upgrade plan trial is finished.

        • Help for the alisa adding

          Sorry, I would like to add a paypal alias on my domain email address. However, the system blocked it. How can I do it?

        • Problem with Writer and Workdrive

          Hi team, I’m the super admin for our Zoho One org. WorkDrive is active, and Zoho Docs is deprecated for our org. However, Zoho Writer cannot connect to WorkDrive at all — we’ve cleared cache, tried incognito, and restarted several times. I was able to

        • Lite plan attachment said 250mb but actually 25mb ?

          Lite plan attachment said 250mb but actually 25mb ? I can't attach over 25mb files, and can't receive mails has attached files over 25mb too

        • Zoho Books | Product updates | August 2025

          Hello users, We’ve rolled out new features and enhancements in Zoho Books. From the right sidebar where you can manage all your widgets, to integrating Zoho Payments feeds in Zoho Books, explore the updates designed to enhance your bookkeeping experience.

        • Constant color of a legend value

          It would be nice if we can set a constant color/pattern to a value when creating a chart. We would often use the same value in different graph options and I always have to copy the color that we've set to a certain value from a previous graph to make

        • Can no longer export as pdf

          In NOTEBOOK I am no longer able to export notes to pdfs as I used to be able to. When I hit that command it asks where I want to send it, but no matter what I chose there is no pdf attachment that shows up in order to send. Nothing happens.

        • Option to Customize Career Site URL Without “/jobs/Careers”

          Dear Zoho Recruit Team, I hope you are doing well. We would like to request an enhancement to the Career Site URL structure in Zoho Recruit. In the old version of the career site, our URL was simply: 👉 https://jobs.domain.com However, after moving to

        • Old vs New Value for Deleted Lookup Values

          Suppose the following scenario, where a value in a lookup is deleted: 1. User has countries form 2. Form A has a lookup to countries form 3. User selects Italy in Form A and saves it with the Italy ID 4. Form A report shows Italy 5. Italy is inadvertently

        • Desktop app doesn't support notecards created on Android

          Hi, Does anybody have same problem? Some of last notecards created on Android app (v. 6.6) doesn't show in desktop app (v. 3.5.5). I see these note cards but whith they appear with exclamation mark in yellow triangle (see screenshot) and when I try to

        • Next Page