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

• My client requires me to have custom pdf file names to except payment for invoices, how can I customize this before emailing.

  Hello! I love the program so far but there are a few things that are standing in the way. I hope you guys can code them in so I can keep the program for years to come. My client requires I customize the pdf file names I send in for billing. Can you please

• Edit Project Number?

  Hi all: We just signed up for a trial of zoho one, which includes ZoHo Projects. We've noticed there was a 'dummy project' preloaded in projects to help familiarize yourself with the software. We've created a couple of our own projects now but noticed since the dummy project was preloaded, our projects start with number 2 then 3, sequentially. Since it seems we will be keeping zoho past the trial, If we delete the dummy project, how do we get our own projects renumbered, beginning with 1? We'd like

• Download pricebook products & details - not just pricebook creation date & name

  We're looking to download a copy of a pricebook and its associated products & book prices (as we have several offices in different countries selling the same products), however, when using the export feature under Data administration it only gives me

• 554 5.1.1 – Mail sending blocked for the domain(s): [gmail.com]

  Here's your corrected text: Hello, I hope you are doing well. I was unable to send a message and received the following error: "554 5.1.1 – Mail sending blocked for the domain(s): [gmail.com]" I tried to send and deliver an email but got this error. I

• Outgoing Mail Blocked – Suspicious Login Activity (Need Clarification and Solution)

  Hello, I’m currently facing an issue where my Zoho Mail account has been blocked due to “suspicious login activity,” and outgoing emails are restricted. Here are the details shown: Block type: Outgoing mail blocked Reason: Suspicious login activity A

• Assign Meeting in records

  It would be nice to be able to "call and assing" meetings from a record, for example from a Deal. Right now - calendar is synced with CRM - meetings show in calendar - you can go in each meeting and assign it to a record It would be nice to be able to

• 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

• ERROR: "Please enter a valid Phone"

  WHAT IS THE PHONE FORMAT? There is nothing ANYWHERE to define the format. At least the error should either show the correct format or provide a link to the help file I enter a valid phone number in as many formats as I can think of and none of them allow me to save the number to CRM Nothing works! No matter what format I enter I keep getting a red error "Please enter a valid Phone" The international format for MY mobile is +61414652366 (or +61 414 652 366) Local format is 0414652366 I call all over

• Introducing Zoho Sprints 3.0

  Zoho Sprints is consistently evolving in steady increments. The introduction of the latest version, with its enterprise level solutions, brings to you advanced capabilities that propel your agile efforts in the right direction. Here's a quick glimpse

• Transaction Rules & Customer Payments

  So I have a situation as follows. We have many clients who are all invoiced on the 1st of each month on a recurring invoice for 1 of 10 plans. This means that almost all payment dates are the same (some people pay late) and that a lot of the amounts are

• Customize Sign-out Button

  Are there some url parameters I can use to make a form button sign-out the user from the app? The sign-out link on the top right is small. Here's and example of the url for the top right sign-out: https://creator.zoho.com/logoutpage.jsp?sharedBy=niskypto&appID=212085000006568003&appLinkName=MYAPP&signOutUrl=niskypto/MYAPP/view-login/SOMEPAGE Note: In my account, the sign-out is set to redirect users to my website. Can I also override this with some url parameters? John M. Whitney

• Please can the open tasks be shown in each customer account at the top.

  Hi there This has happened before, where the open tasks are no longer visible at the top of the page for each customer in the CRM. They have gone missing previously and were reinstated when I asked so I think it's just after an update that this feature

• Tip #65 - Exploring Technician Console: Short Keys - 'Insider Insights'

  Hello Zoho Assist Community! Have you ever been in the middle of a remote support session, trying to pass a key combination onto the remote machine, only to find it's reflecting on the technician's computer. The Short Keys feature in Zoho Assist is here

• Reading from and writing to Zoho Projects Custom Module with Deluge

  Does anyone know if there is a way to read from and write to the Custom Modules that Zoho now supports. I would love to be able to loop through a set of data and create the entities I need to for this new custom module I'm looking to put together.

• Disappointment with Zoho Payments

  Dear Gowdhaman, I am writing to inform you that I am removing Zoho Payments from my website. I cannot continue to disappoint my customers due to the lack of UPI support, as has been the case with my experience so far. Please note that the 0.5% transaction

• Evolução do modelo de ambientes: Dev, Homologação e Produção com pacotes versionados

  Hoje o Zoho CRM já oferece Sandbox, o que é um avanço importante para organizações que trabalham com customizações mais complexas. No entanto, na prática, o modelo atual ainda apresenta limitações significativas quando múltiplas equipes ou consultorias

• Permissões granulares por usuário além do modelo baseado exclusivamente em perfis

  Atualmente, o modelo de segurança do Zoho CRM é fortemente baseado em perfis. Embora funcional, esse modelo apresenta limitações quando equipes possuem variações individuais de acesso dentro do mesmo grupo operacional. Em cenários reais, é comum que usuários

• Add or update lookup field values during Blueprint transition

  Hello everyone, During blueprint transition users can add or modify the value of a lookup field. For instance, if the Tickets module includes a lookup field that connects it to records in the Assets module, agents can link the ticket to the correct asset

• Can you limit SEO penalties by delaying the appearance of a pop-up?

  Google is not keen on pop-ups and has got even less keen on them with the new Core Web Vitals updates. But I like using pop-ups. If you delay the pop-up so it only appears 10 seconds after the page loads, do you avoid Google’s penalties? 

• Adding bank details to the contact through API

  How to add bank-related information to the contact while creating it using API? The account number needs to be encrypted before sending it through API but not sure how to encrypt and get those values. Please guide me in this.

• Restrict Payment Methods

  Allow us to restrict certain payment methods specific for each customer.

• Clone Banking Transaction

  Why is there no option to CLONE a Transaction in the Banking module?? I often clone Expenses (for similar expense transactions each month) so I would also like to clone Income transactions. But there is no option in Banking to clone an existing Income

• PDF limit

  Hello everyone, We have received an e-mail that we have reached our PDF limit. (see screenshot) However, I cannot find any reference to a PDF limit in our tariff plan (Premium). (see screenshot). What is the maximum number of PDFs that can be generated

• How can I see content of system generated mails from zBooks?

  System generated mails for offers or invices appear in the mail tab of the designated customer. How can I view the content? It also doesn't appear in zMail sent folder.

• Credit Card Pre-Authorization with later Capture/Settlement

  We really enjoy the convenience of being able to pay off a customer's invoice using our Auth.Net integration with Zoho Books. Unfortunately, we can only take advantage of this feature with a small percentage of our customers as it leaves a gaping hole

• Zoho Projects and CRM Integration in Analytics

  Hi Team, In Zoho CRM, I’ve integrated CRM with Zoho Projects and associated a project within the CRM. The integration is visible under the Deals module. However, I’m unable to find this data in Zoho Analytics. Does anyone know where this information is

• Accessibility in Zoho CRM: Not just a feature—a way to empower

  For instructions on setting up these controls, please check this help document: Configuring accessibility controls. Hello everyone, Today (December 3, 2024), on the International Day of Persons with Disabilities, we begin our journey towards a CRM that

• Automation Series #1: Round Robin vs Direct Assignment in Zoho Desk

  Direct Assignment vs Round Robin: Choosing the right routing method in Zoho Desk This post is part of the "Desk Automation Series," Chapter 1. Through this series, we will help you choose the right automation type in Zoho Desk by comparing commonly confused

• Invalid tax authority ID.

  How do I correct this ?

• Pay Pal Paylater button

  I am testing the paypal setup to have my customers pay invoices with paypal and credit cards. But it seems to have two options. Paypal and Pay later. I don't want my customers access to pay later feature. How can I turn that part off.. My other integration

• Zoho Workshops are coming to the Netherlands - Join us on 14-16 April in Amsterdam!

  Dear Zoho Community Members, After succesful recent editions in the UK and Scandinavia, we’re pleased to invite you to the upcoming Zoho Benelux Workshop 2026, taking place 14–16 April 2026 in Amsterdam. This three-day, in-person event at the Park Plaza

• How to install Widget in inventory module

  Hi， I am trying to install a app into Sales Order Module related list, however there is no button allow me to do that. May I ask how to install widget to inventory module related list?

• Sub form auto field population based on parent form

  I have a parent form called "Sites" with a text field called "Site". I have a subform called "Design Comments" (actual form name "Review Comments") with a lookup field name "Sites1" that looks up from the Sites form. I want the Sites1 lookup field to

• Building Toppings #7 - Using schedules and workflow functions

  Hello Biginners, In our previous forum post, we explored install and uninstall actions and learned how to trigger custom logic the moment a topping is added or removed from an organization. In this post, we'll look at how to automate actions during regular,

• Simplify scripting with Zia assistant bot

  Hello everyone, Building automation using Deluge custom functions gives users flexibility and control. Traditionally, creating these functions required writing scripts, testing the logic, and validating the configuration before using it. With Zia assistant

• Zoho Sprints iOS app update: Global view, screen capture control, file encryption, tags enhancement

  Hello everyone! We are excited to introduce new features in the latest version(v2.1) of the Zoho Sprints iOS app update. Let’s take a quick look at what’s new. 1. Global view Global view brings all your project items into one centralised space. You can

• Resource Management System built using Zoho CRM, Creator, Projects, and People:

  In a Resource Management System built using Zoho CRM, Creator, Projects, and People: CRM Deal Closed → Creator Allocation Engine → Zoho Projects Task Assignment What is the recommended architecture to handle dynamic reassignment when: an employee goes

• Request to Remove LinkedIn Verification from My Emai

  I would like to submit a complaint regarding my Zoho Mail account. I previously used this email address to verify a LinkedIn account, but that LinkedIn account has now been closed. I need to remove or cancel the verification associated with the closed

• Pin multiple columns and adjust column widths in CRM subforms

  Hello all, Subforms act as secondary forms or tables in which you can associate multiple line items to a primary record and thereby ensure more structured and comprehensive data organization. We've made some recent enhancements to subforms. Here's what's

• Removing To or CC Addresses from Desk Ticket

  I was hoping i could find a way to remove unnecessary email addresses from tickets submitted via email. For example, a customer may email the support address AND others who are in the helpdesk notification group, in either the TO or CC address. This results

• Next Page