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

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



Hello everyone!
Welcome back to another week of Kaizen!

We released the Queries feature sometime back and hope you have tried it out.

A little gist about this feature before we move on to our post.

Zoho CRM's Queries feature enables dynamic data retrieval from both CRM modules and external services, facilitating seamless integration and informed decision-making.

Key Components

  • Sources: Pre-configured sources like Modules and COQL are available, with the option to add custom sources via REST APIs.
  • Queries: Fetch data by selecting modules, writing COQL statements, or specifying REST API endpoints, headers, and parameters.
  • Variables: Incorporate variables in criteria, COQL statements, and endpoints to pass dynamic values during execution.
  • Schema: Auto-generated schemas define the structure of query responses, with editable paths, field types, and labels for customization.
  • Serializer: Utilize JavaScript to manipulate and customize query responses, ensuring data is in the desired format for further processing.

Types of Queries

  • Modules: Retrieve records by selecting specific modules and fields, applying conditions to filter data as needed.
  • COQL (CRM Object Query Language): Write SQL-like queries to fetch data, supporting complex operations like joins and aggregations.
  • REST API: Fetch data from external services by specifying endpoints, headers, parameters, and connections.

With the Queries feature, you can efficiently access and display relevant data within Zoho CRM, enhancing workflow efficiency and decision-making capabilities.

A little insight into Functions before we dive into today's Kaizen!

Functions, Queries, you get the connection, right? Read on!

Many of us use Functions in Zoho CRM extensively to perform our business logic and customize the way things work in Zoho CRM. You can use Functions in blueprints, workflows, Circuits etc.

Let's say you have a function that gets the employee records from the Employees module. Technically, the function executes an API call or an integration task, and gives a response.

The response can be a string or map(JSON), depending on how the function is written and where it is used. Since functions can be used in many places, the same response format may not be the right one to be used in a circuit or a workflow.

This is where the genie 'crmAPIResponse' object comes into picture!

The power of the 'crmAPIResponse' object

The crmAPIResponse object to be returned in the CRM function should encapsulate the response in a way that it can be used in Queries, Circuit, workflow etc. The details needed are encapsulated as a map. It should include details like crmStatusCode, status, message, body in order to construct the desired format for handling data and customizing the error handling logic.

Let's consider the following example function where we use the getRecordByID integration task.

The response of the integration task contains all the fields in that module, but we want only certain parts of the response JSON and also add custom error messages, to be used in other components like Queries, Circuits, etc,.

Here is the code.
{
leadId = "3652397000018025772"; // Replace with a valid Lead ID

// Initialize customAPIResponse map
customAPIResponse = map();

// Fetch lead details
crmResponse = zoho.crm.getRecordById("Leads", leadId);

// Log the raw response for debugging
info "CRM API Raw Response: " + crmResponse;

// Validate and process the response to include only the required fields
if (crmResponse != null && crmResponse.containsKey("id"))
{
// Extract required fields
filteredData = map();
filteredData.put("id", crmResponse.get("id"));
filteredData.put("Last_Name", crmResponse.get("Last_Name"));
filteredData.put("Email", crmResponse.get("Email"));

customAPIResponse.put("crmStatusCode", 200);
customAPIResponse.put("status", "success");
customAPIResponse.put("message", "Lead data retrieved successfully.");
customAPIResponse.put("body", filteredData); // Include only filtered data
}
else
{
customAPIResponse.put("crmStatusCode", null);
customAPIResponse.put("status", "error");
customAPIResponse.put("message", "Invalid or null response from Zoho CRM API.");
customAPIResponse.put("body", null);
}

// Return the customAPIResponse
return {"crmAPIResponse": customAPIResponse};

}


Here, you can see that we have parsed the response of the integration task to get the Last_Name, Email, and record ID using the crmResponse.get("field_API_name") statement and constructed the customAPIresponse object using the customAPIResponse.put("key", "value") statement.
The statement return {"crmAPIResponse": customAPIResponse}; returns the response body as depicted in the previous statements.

Response to the info "CRM API Raw Response: " + crmResponse; statement
"CRM API Raw Response: {"Owner":{"name":"Patricia Boyle","id":"3652397000000186017","email":"p.boyle@zylker.com"},"$field_states":null,..}}}


Response of the return {"crmAPIResponse": customAPIResponse}; statement

{
    "crmAPIResponse": {
        "crmStatusCode": 200,
        "status": "success",
        "message": "Lead data retrieved successfully.",
        "body": {
            "id": "3652397000018025772",
            "Last_Name": "Math",
            "Email": "math@gmail.com"
        }
    }
}

Error response

{
    "crmAPIResponse": {
        "crmStatusCode": null,
        "status": "error",
        "message": "Invalid or null response from Zoho CRM API.",
        "body": null
    }
}

You can see that we have used the crmAPIResponse object to get only the required keys from the response and constructed a much simpler response.
Refer to our help page on Response Object for more details.

Finally, to today's Kaizen!

We've established that you can use the crmAPIResponse object to construct responses in a way that's suitable to be consumed at another place like a circuit or a workflow.
We also know that Queries allows you to have sources of the REST API type to fetch data from various sources. This means that you can have a standalone function that is enabled as a REST API as a source in Queries.

Let's see an example.
There is a simple function that uses the getRecords integration task to get the records from the Employees module.
I have used the crmAPIresponse object to construct a response as shown in the following code.

string standalone.getRecords()
{
result = zoho.crm.getRecords("Employees");
response = Map();
response.put("status_code",200);
response.put("body",{"code":"success","details":result,"message":"function executed successfully"});
return {"crmAPIResponse":response};
}

The response of this function is a string in the crmAPIResponse object as shown in this image.


  1. Save this function and enable REST API.

  2. You can see that the domain is https://www.zohoapis.com. To be able to use this in a Query, register this domain in Trusted Domain.

  3. To create a REST API type source, you must add the source. Go to Setup > Developer Hub > Queries > Sources tab.
  4. Click Add Source and give the details like the name, base URL, headers, and parameters under the Information section.

  5. Click Save.
  6. Go to the Queries tab and click Add Query.
  7. For Source, choose the source you just added.
  8. Under Information, enter the name, API name of the query.
  9. For the endpoint, enter the API Key URL of the function.

  10. Enter the parameter name and values in the Parameter field.
  11. Click Add Serializer if you want to serialize the response. In this example, I have serialized the response to include only the Name, Email, and Position fields in the output. The result contains the 'body' object that we returned in the crmAPIResponse object of the function.

  12. Click Save to save the serialization.
  13. Click Next to view the schema of the query. Make changes as required.
  14. Save the query.
You can now use this query in Canvas or associate it with Kiosk to solve your business needs.

Let us see how the crmAPIResponse object in the function affects the response of the query.

Query with the function without crmAPIResponse:

Let's consider that the function getRecords() does not use the crmAPIResponse object. In that case, the function returns a response that is a string. This response string cannot be serialized or used elsewhere.


Schema of the query without crmAPIResponse:


Query with the function with crmAPIResponse and serialization:

The same getRecords() function that uses the crmAPIResponse object allows you to construct the response as JSON. You can serialize this response easily and use it in a circuit, query, workflow etc.


You can see here that the response is now a JSON.

Schema of the query with crmAPIResponse:



In conclusion, you can use the crmAPIResponse object in Functions to construct the desired response and use the REST API-enabled function as a source in Queries.
Leveraging the advantage of the crmAPIResponse object in functions and using it in Queries increases the prospect of solving many more business cases easily and customize more efficiently.

We hope you liked this post and found it useful. Let us know your thoughts in the comments.
If you'd like us to cover any other topic in this series, feel free to comment or reach us at support@zohocrm.com.



Cheers!

------------------------------------------------------------------------------------------------------------------------------------------------
Info
More enhancements in the COQL API are now live in Zoho CRM API Version 7. Check out the V7 Changelog for detailed information on these updates.








      • Sticky Posts

      • Kaizen #198: Using Client Script for Custom Validation in Blueprint

        Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

      • Kaizen #226: Using ZRC in Client Script

        Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In this

      • Kaizen #222 - Client Script Support for Notes Related List

        Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore how

      • Kaizen #217 - Actions APIs : Tasks

        Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.

      • Kaizen #216 - Actions APIs : Email Notifications

        Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are

        • Recent Topics

        • Automatically create an Delivery Challan basis a Sales Order.

          Hi, I wanted to know if there is a possibility to automatically populate a Delivery Challan basis a Sales Order. Is it possible to do this with custom functions? If yes, how? 

        • Zoho Form URL displays incorrect name

          Hi, I have a form I created called "Design Request form". It displays this way everywhere I look. However, in the URL, it shows up as "DesignJobRequestFormFINAL011325PROOFV1B" and I'm not sure why. I can't find where to fix this. Does anyone have any

        • Introducing Radio Buttons and Numeric Range Sliders in Zoho CRM

          Release update: 1. 2 March 2026: Currently out for CN, JP, AU and CA DCs (Free and standard editions). For other DCs, this will be released by mid-March. 2. 26 March 2026: CA, SA, AU, JP, CN DCs - Free, Standard, Professional, Enterprise, Ultimate, CRM

        • Finding rhythm through poetry

          Poetry has long been a powerful form of expression, discovery, and reflection. For many, it is a way to pen down their thoughts and experiences. The "poetic license" allows writers to shape their words with rhythm and flow. This year, on World Poetry

        • Zoho Desk Ticket SLA Level

          Hello, we have 2 levels of SLA escalation for our Tickets. Is there a way to display on the ticket information the level of SLA escalation the ticket currently on? I am aware that we can see in the ticket history the level of escalation that has been

        • Allow Font Size 11 in Editors...

          That is basic functionality...

        • 【まだ間に合う！】Zoho ユーザー交流会 | AI活用・CRM・Analytics の事例を聞いて、ユーザー同士で交流しよう！

          ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 3月27日(金)に東京、新橋で開催する「東京 Zoho ユーザー交流会 NEXUS」へのお申し込みがまだの方は、この機会にぜひお申し込みください！（参加無料） ーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーー イベントの詳細はこちらから▷▷ https://www.zohomeetups.com/tokyo2026vol1#/?affl=communityforumpost3 ーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーーー

        • Where is the scheduled report in New UI?

          Hi Team, Seems there is not such a field in New UI, hence I have to switch to old UI to handle request..

        • Building a Simple Raspberry Pi + Keypad IoT PoC with Zoho Flow

          I want to share a simple IoT PoC I recently built that connects a Raspberry Pi to Zoho Flow and Zoho Creator. The goal was to send PIN input data from a hardware keypad to Zoho and trigger a servo and buzzer for visual/audible feedback. This can serve

        • What's New in Zoho Billing | January 2026

          Excited about the latest enhancements in Zoho Billing? Our January updates bring an intelligent AI assistant, smarter subscription management, and improved tax compliance, saving you time and reducing manual work. Dive into the details below to see how

        • Is there a way to sell in a practical method multiple subscriptions of the same product? i.e. domain names

          In evaluating Zoho Billing, a hurdle to adopting it is that Zoho Billing does not seem designed to support businesses that sell multiple subscriptions of the same product. In our case, we need to sell and manage several domain names per client. Am I right

        • Update P_Leave: code: 7052 "Employee_ID": "Enter Employee ID"

          Hi, Zoho People - Update Leaves Can someone assist? ------------------------------------------------------------------------------------------ col = Collection(); col.insert("recordid":id); col.insert("Date_Check_Approval":zoho.currentdate); info zoho.people.update("P_Leave",col.toMap());

        • Can't change form's original name in URL

          Hi all, I have been duplicating + editing forms for jobs regarding the same department to maintain formatting + styling. The issue I've not run into is because I've duplicated it from an existing form, the URL doesn't seem to want to update with the new

        • Can't rename groups on Mac desktop app

          I'm working on an up-to-date Mac with a freshly downloaded Notebook app. I'm trying to rename a group within a notebook. Here I have, left to right, a note, a group, and a note. I select the group. On the top left, I select Action. On the dropdown, "Rename"

        • Strange behavior in CRM Number Field – Characters allowed but not "e"?

          Hi everyone, Has anyone faced this strange issue in Zoho CRM? In a Number field, it is possible to type some characters, but the character "e" cannot be entered. This was really surprising to me. Normally, a number field should restrict all characters

        • Best Way to Manage Approvals Within Blueprint Stages?

          Hi, I am working on a requirement involving Blueprint and approval logic in Zoho CRM and would appreciate some guidance. I understand that approval processes do not trigger when a record is currently within a blueprint, which makes it challenging to implement

        • Marketing Tip #25: Grow your social presence with a simple posting routine

          Consistency is one of the biggest growth drivers on social media. Regular content keeps your store visible and helps customers remember you. Even 3–4 posts a week can build momentum over time. The easiest way to stay consistent is to stop trying to create

        • How to update "Lead Status" to more than 100 records

          Hello Zoho CRM, How do I update "Lead Status" to more than 100 records at once? To give you a background, these leads were uploaded or Imported at once but the lead status record was incorrectly chosen. So since there was a way to quickly add records in the system no matter how many they are, we are also wondering if there is a quicker way to update these records to the correct "Lead Status". I hope our concern makes sense and that there will be a fix for it. All the best, Jonathan

        • Bring your own credentials (BYOC) for connections in Zoho Creator

          Hello everyone, We're excited to announce an important step forward in how integrations and authentications work in Zoho Creator. Zoho Creator is a versatile platform for integrations, enabling you to connect with thousands of third-party services using

        • Project Management Bulletin: March, 2026

          We are passionate about equipping our users with efficient solutions that help them run their businesses successfully. Our collective efforts over the past 2 years have culminated in the launch of Sprints 3.0— built with reliable features, impactful integrations,

        • Composite items inside of composite items; bill of materials needed

          Hi Zoho and Everyone, I am evaluating whether Zoho Inventory will work for my small business. I grow and harvest herbs and spices but also get from wholesalers. I use all these items to make herbal teas, but also sell them as individual items on my Shopify store and Etsy. I discovered the composite item bundling and am wondering if I could get some assistance since there is no bill of materials: Our herbal company's best selling tea is a sleepytime tea. Sleepytime Tea can be purchased in three weights

        • Automation Series: Sync Task Status with Zoho Desk Tickets

          In Zoho Projects, you can automatically close and reopen an associated Zoho Desk ticket when the status of a task is changed. This syncs the current state of the task with the support ticket without manual updates. For instance, a support team handling

        • Auto-Generate Line Numbers in Item Table Using HTML & CSS Counters (Zoho Books & Zoho Inventory Custom Templates)

          <div> <style> /* Start counter from 0 inside tbody */ tbody#lineitem { counter-reset: rowNumber; } /* Increment counter for each row */ tbody#lineitem tr { counter-increment: rowNumber; } /* Show counter value in first column */ tbody#lineitem tr td:first-child::before

        • Does zoho inventory need Enterprise or Premium subsrciption to make Widgets.

          We have Zoho One Enterprise and yet we can't create widgets on inventory.

        • Zoho CAMPAIGNS working hours

          Hi I use Campaigns Automation workflows to automate follow-ups to my Leads. I discovered this weekend that emails are being sent out on Sundays. How do I limit my Campaigns outgoing emails to business working hours? This is very important! Thanks, D

        • Depositing funds to account

          Hello, I have been using Quickbooks for many years but am considering moving to Zoho Books so I am currently running through various workflows and am working on the Invoicing aspect. In QB, the process is to create an invoice, receive payment and then

        • Create Receipt of a Donation (not a sale)

          We are a non-profit organization that receives general donations. How do I create a receipt of payment for the donor and categorize the payment as a Gift? I tried the method of creating an invoice; however that automatically created a "Sales" transaction

        • Function #2: Create a Deal in Zoho CRM when an Estimate is created in Zoho Books

          For those who use Zoho CRM integrated with Zoho Books, here's a nifty function that helps you optimize your sales process by adding a Deal in Zoho CRM whenever an estimate is created in Zoho Books. Custom Function: To create the custom function, go to

        • New Custom View -Sorting the Custom fields

          While creating a New Custom View in invoice , Customers, Bills ,expense etc , the sorting of custom fields are not available , a query function "order by / sort by  " may also be included in  Define new criteria module  which will be more beneficial to

        • Grouping Undeposited Funds to Move to other accounts

          In the bank option it would be nice to check what transactions in undeposited funds I want to move to other accounts. Then while checking this it can accumulate totals and created whats essentially a deposit slip. Once the transaction is moved it should

        • Sync your CRM Tasks with Zoho Projects

          Zoho Projects integration with Zoho CRM helps you manage your tasks more efficiently. You can create all project related activities right inside your CRM using this integration. Create new portal or associate an existing portal, add projects to the portal,

        • Zoho CRM strips whitespace in text fields

          When editing field text with multiple spaces: CRM - both UI and API trim / compress the whitespace to a single space when saving: Is this known / expected / documented behaviour?

        • Custom Button makes scroll bar go down in report

          I have a report with a Custom button called Completed. A colleague mentionned to me that when he pressed this custom button it scrolled down the page which is annoying since he want to stay at the same space on the repoort. There is no reload linked to

        • Quickbooks Integrations Stopped Working

          All of our Quickbooks integrations have stopped working. I am checking in to see if: a) this is a known issue b) if anyone else is having this issue. As usual, Zoho support is unavailable.

        • Incorrect Functioning of Time Logs API (Version 3)

          We need to fetch the list of time logs for each task for our company internal usage. We are trying to achieve it by using the next endpoint: https://projects.zoho.com/api-docs#bulk-time-logs#get-all-project-time-logs Firstly, in the documentation the

        • Dynamic image in form works in the app but not on the customer portal.

          img = frm_Fichas[ID == input.Nombre].Foto; imgno = Nophoto[ID2 = 1].Image; if(len(img) > 1) { img = img.replaceAll("/sharedBy/appLinkName/",zoho.appuri); img = img.replaceAll("viewLinkName","Fichas_de_personal_public"); img = img.replaceAll("fieldName","Foto");

        • Uplifted homepage experience

          Editions: All editions. Availability update: 17th February 2026: All editions in the CA and SA DC | JP DC (Free, Standard and Professional editions) 23 February 2026: JP (All Editions) | AU, CN (Free, Standard, Professional editions) 27 February 2026:

        • Approval Workflow for Purchase Orders Abrir

          The requirement is , that all purchase orders greater than or equal to 5000 go through an approval process from certain people, but within books I only see that the approvers can be by levels or any approver but we cannot enter a rule like these. Can

        • WeTravel + Zoho CRM Integration - Has Anyone Built a Connector or Extension?

          Hi all, I'm exploring options for integrating Zoho CRM with WeTravel (booking & payment platform for tour operators). Zapier seems to be the common method but seems limited. I'm wondering if anyone in the community has developed a more comprehensive solution,

        • Option in pipeline deal to select which hotel or branch or store if client has more than one local store

          Hi, I would like to know if there is an option in the deal pipeline to select which hotel, branch, or store a deal is related to—if the company has more than one location. For example, I have a client that owns several hotels under the same company, and

        • Next Page