Kaizen #197: Frequently Asked Questions on GraphQL APIs

🎊 Nearing 200th Kaizen Post – We want to hear from you!

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. 

Got ideas? Tell us! ✨

Hi all,

Hello and welcome to another week of Kaizen!

In this post, we will be discussing Frequently Asked Questions on Zoho CRM GraphQL APIs.  GraphQL is a query language that provides a more flexible and efficient way to access data and metadata within your Zoho CRM organization. 

Why should I try GraphQL APIs?

 Using GraphQL with Zoho CRM allows you to fetch exactly the data you need in a single request, reducing over-fetching and under-fetching. It also enables you to combine multiple operations in one request, which can improve performance and reduce network overhead.

How do I authorize GraphQL requests?

Similar to Zoho CRM REST APIs, GraphQL APIs use OAuth 2.0 for authorization.

For self-clients, you can use the self-client option in the API console to get an authorization grant code. This code can be exchanged for an access token and a refresh token. Once you receive the access token, send the token in your HTTP authorization header with the value "Zoho-oauthtoken {access_token}" for each request. Check out our Postman collection for GraphQL APIs for examples.

Are GraphQL APIs available for all Zoho CRM editions?

GraphQL APIs are available in Enterprise, Zoho One Enterprise, CRM Plus and Ultimate edition of Zoho CRM. Note that it is not available in any trial editions.

What is the difference between REST APIs and GraphQL APIs?

REST APIs let clients talk to servers using standard HTTP methods such as GET, POST, PUT, PATCH, and DELETE. Instead of fetching a fixed dataset like with REST, GraphQL APIs allows you to ask for precisely the data you want. We have covered this topic in detail in our previous Kaizen post that compares REST APIs and GraphQL APIs

Do I need to do any initial setup to start using GraphQL APIs?

To start using GraphQL APIs, you have to enable GraphQL APIs for your Zoho CRM profile through the enable GraphQL API call. 

• Request URL : {api-domain}/crm/graphql/actions/enable
• Method : POST
• Scope: ZohoCRM.GraphQL.UPDATE

This API call generates the GraphQL schema. GraphQL schema defines the capabilities of a server, the data it contains and the actions that can be done on it. Note that it is sufficient to invoke this API call once for each profile. 

What are the operations supported in Zoho CRM GraphQL APIs?

   Currently, Zoho CRM GraphQL APIs support only query operations. Query operation is analogous to the GET method in REST APIs.

How do I configure requests for Zoho CRM’s GraphQL APIs?

• Request URL: {{api-domain}}/crm/graphql 
• Method: POST
• Scope: ZohoCRM.graphql.READ and scope of the corresponding resource.
  

How do I write a basic query in GraphQL? 

The below query can be used to fetch Last_Name in Leads module.

Request body 

query {     Records {         Leads {_data {Last_Name {value}}}     } }

 

Output 

{"data":{"Records":{"Leads":{"_data":[   {"Last_Name":{"value":"Kitzman"}},   {"Last_Name":{"value":"Frey"}}   // ... ]}}}}

What are the supported metadata types that can be fetched using GraphQL APIs?

Using GraphQL APIs you can fetch metadata from Modules, Users, KanbanView, UserProperties, ProfilePermissions, Profiles, Roles, and Widgets

Can I fetch metadata and data of a particular module in a single query using GraphQL APIs?

Yes, using GraphQL it is possible to fetch both metadata and data in a single query. 

 For example, the below query can be used to fetch Last_Name from Leads module and metadata information of the Last_Name field in the Leads module.

Request body

{   Records {     Leads { _data { Last_Name { value } } }   }   Meta {     Modules(filter: { api_name: "Leads" }) {       _data {         fields(filter: { api_names: "Last_Name" }) { _data {                         id                         api_name                         display_label                         json_type                         data_type }}}}}}

 

 Output 

{   "data": {     "Records": {       "Leads": {         "_data": [           { "Last_Name": { "value": "Kitzman" } },           { "Last_Name": { "value": "Frey" } }           // ...         ]       }     },     "Meta": {       "Modules": {         "_data": [           {             "fields": {               "_data": [                 {                   "id": "6660682000000002595",                   "api_name": "Last_Name",                   "display_label": "Last Name",                   "json_type": "string",                   "data_type": "text"    }]}}]}}}}

 

We have covered this in detail in this Kaizen post: Using GraphQL APIs to fetch data in a consolidated way.

Are there any limits applicable for a GraphQL API query?

Yes, Zoho CRM imposes certain limits on the GraphQL API to ensure fair usage. 

• Credits: A single query can consume up to a maximum of 10 credits
• Complexity: Complexity is a measure of workload a query exerts on the server based on the number of fields and depth of the query. The maximum complexity allowed for a single query is 1000. 
• Depth: The nesting level of a queried field is referred to as depth. The limit for metadata is seven, and for data is three.
  

Refer to the official documentation on GraphQL credits.

Is it possible to retrieve selective data using GraphQL APIs?

Records

You can use the where argument to filter records from each module.  Each field can support type specific operators and can be combined with Boolean logic and wildcards.

For example. to fetch Email, Last_Name, ID, Phone and Mobile of  contacts where last name starts with "Ni" and mobile contains the digit 5 or phone number equals 555-678-9999

Request body

{   Records {     Contacts(where: {       and: [         { Last_Name: { like: "Ni%" } },         {           or: [             { Phone: { equals: "555-678-9999" } },             { Mobile: { like: "%5%" } }           ]         }       ]     }) {       _data {         Email { value }         Last_Name { value }         id { value }         Phone { value }         Mobile { value }   }}}}

 

Introspecting the GraphQL schema in Postman will reveal the details of fields and supported operators for each module. Check out our previous Kaizen, where we explained this using videos.

Metadata

You can use the filter argument to filter metadata resources.

For example, the query below fetches metadata of Deals module and api_name of its layouts and fields

Request body

query {   Meta {     Modules(filter: { api_name: "Deals" }) {       _data {         id         singular_label         plural_label         layouts {           _data {             id             api_name           }         }         fields {           _data {             api_name      }}}}}}

How do I paginate results in GraphQL?

In GraphQL, we use the offset and limit argument to paginate results.

You can use offset to fetch the next page of results by passing the value from your previous response, starting with null for the initial set.  For each page, the number of records has a limit: up to 100 records for root queries or 10 for nested data.

The value to be passed in offset is obtained by querying for previous_offset and next_offset inside _info object.

Is it possible to sort records in GraphQL? 

The order_by argument can be used to sort the response set after fetching records to ascending or descending order.

For example, the below query fetches the fields Deal_Name, Expected_Revenue, and Probability from Deals module in descending order of probability.

Request body

query {   Records {     Deals(order_by: { Probability: { order: DESC } }) {       _data {         Deal_Name { value }         Expected_Revenue { value }         Probability { value } }}}}

When should I choose Zoho CRM GraphQL APIs over Zoho CRM REST APIs, and vice versa? 

Use Zoho CRM GraphQL APIs when:

• You need to fetch complex, nested data from multiple resources (e.g., accounts with linked contacts and deals) in a single request and avoid under-fetching of required data/metadata.

• You need to minimize over-fetching of data/metadata by selecting only specific resources, fields of the resources, and relationships of the resources.

• You need to query data and metadata together efficiently. 

Use Zoho CRM REST APIs when :

• You need to perform simple CRUD operations (e.g., fetch/update a single product).

• Your use case involves straightforward endpoints without nested data/metadata.

• You need to do add/update/delete operations.

We trust that this post addressed your doubts on GraphQL APIs. If you have any questions please let us know in the comment section or reach out to us at support@zohocrm.com.

Previous Kaizen Post : Kaizen #196 - Zoho CRM Queries - Best Practices|Kaizen Directory

• Topic Participants

• Mable Mary M P

  

• Andres

• qasim

• Malik Faisal Ijaz

• Thomas James

• 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

• How to Print the Data Model Zoho CRM

  I have created the data model in Zoho CRM and I want the ability to Print this. How do we do this please? I want the diagram exported to a PDF. There doesnt appear to be an option to do this. Thanks Andrew

• our customers have difficult to understand the Statements

  our costumers have big problems to understand Zohos Statements. we need a text box after the payment number to explain what the payments are for. Is it possible to develop a version of the Statement with that kind of box and if so whu can do it

• How to track a list of ALL the items that ONE customer bought?

  Hello, I am interested in getting a list of all the items that only ONE of my customers bought, and the invoices are what show up instead. It's very tedious to go through every single invoice when we sell a lot of items to this customer. Surely there

• Exchange Rate Updates

  Hi, It would be great that when you work with multiple currencies, the exchange rate updates automagically every day (as seen on Zoho Books) or at least that when you create/update an opportunity the exchange rate could be manually updated, or maybe both!

• Locked Out of Super Admin Account

  I'm locked out of my Super Admin account and the external e-mail is no longer associated with it. There seems to be a problem during set up, the system ought to ask to assign a new password instead of using Google accounts. Please help me get back access.

• Emails are going to notification folder and not in inbox

  emails are going to notification folder and not into inbox

• 550 5.4.6 Unusual sending activity detected. Please try after sometime

  Hi, I am receiving this error message when trying to send my emails. The only reason I can think why this is happening is my previous two emails were bounced back to me due to a non working mailbox error. I have followed the online links for unblocking

• Projects Home Customization

  Hello! We've been in Zoho One since July of last year, and my team has started providing feedback on what they'd like to do. Their latest wish is that they could have more control over the Projects Home content. For example, they want a card that shows

• IMAP search support

  Does Zoho Mail support IMAP search? https://www.rfc-editor.org/rfc/rfc9051.html#name-search-command TEXT <string> Messages that contain the specified string in the header (including MIME header fields) or body of the message. Servers are allowed to implement

• Performance is degrading

  We have used Mail and Cliq for about three years now. I used to use both on the browser. Both have, over the past 6 months, had a severe degradation in performance. I switched to desktop email, which appeared to improve things somewhat, although initial

• Cannot reorder fields in Page Layout in Expenses and Purchase Requests

  It is very inconvenient that the custom fields in Page Layout cannot be re-ordered. The only way is to remove the fields and re-create them; however, it is impractical. This would affect the reports and dashboards we are having. Not able to re-order the

• bouncing emails

  My recurring invoices have bounced back

• Probable Scam / Phising attempt from email pretending to be Zoho

  I think this is a scam email right? It says "zohCworkplace.com". I'm on the Mail Free plan The link in the CTA button seems to go to a redirect. Just wanted to bring it up to the security team.

• Email Address Search in "To" Field Search is broken, Zoho refuses to fix it

  Typing a part of the email address string other than the beginning of the string does NOT work, I kindly urge Zoho to fix this. Let's say you remember writing an email so someone called "smith" from company "corp.com", but can't remember their first name,

• Emails not being received by @hotmail.com, @outlook.com and a few others

  When I try to send emails from zoho mail to people with email addresses ending @outlook.com and @hotmail.com (and a few others), I get a 'delayed' automatic email and then a few hours later, an 'undelivered' automatic email. This has started a few months

• scroll bar for far left of screen

  I am unable to even see the scroll bar to the right of "inbox" etc on the left; it is stuck at "streams" and I can't get to inbox or anything else. It would help if it could be made a lighter color as the black or dark grey can't bee seen.

• OUt of office every friday

  Hi, I tryed to configure my out of office, because i'm not working or emailing on fridays. But when i select only friday as unavailable day, the out of office still sets for the whole week. What am I doing wrong?

• Signature line

  How do I set signature line in email

• Zoho email

  I cannot send email to mail.ru

• Something wrong with client script??

  Someone have the same feeling? Client script behavior become very strange..

• 【参加無料】東京 Zoho ユーザ交流会 NEXUS ー CRMで始めるマーケティング事例 / AI活用法(Zia Agents)

  ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 3月27日(金)に東京、新橋で東京 Zoho ユーザー交流会 NEXUS を開催します！ 昨年度までより、さらにパワーアップして戻ってきました！ ユーザー活用事例は、2人のユーザーさんからお話しいただきます。Zoho サービスの活用の幅を広げたい方や、他のユーザーの利用法を気軽に知りたい方など、多くの方にとって学びのあるセッションになること間違いなしです✨ また今年は、これまで以上に、AI機能にも焦点を当てて行く予定です。 初回として、Zoho社員からZoho

• Issue Exporting Data – CSRF Token Invalid Error

  Dear Zoho Team, We are experiencing an issue when exporting data from our Analytics workspace. Whenever we attempt to export data from our analytical pool, the system displays the following alert message: Alert Message: The CSRF token is invalid. It could

• Zoho Mail 505 error I can not send email

  Hi, I’m having issues sending emails from my custom domain email address. When I send emails to Outlook addresses, I receive an “Undeliverable 505” error. However, emails send and receive correctly when I use Gmail. This is important for my business,

• Multiple MFA Methods

  With SMS-based MFA methods being discontinued, there is now no way to have mutliple MFA methods. I'd like to add my zoho account on two seperate phones using the Google Authenticator app. In the https://accounts.zoho.com/home#multiTFA/modes you can only

• Reuse Standalone Function

  I noticed that there's a missing information in documentation to reuse a standalone function and it is because the parameters require an argument. Here is my code and it is working. response = invokeurl [ url: "https://people.zoho.com/api/v3/function/sample/execute"

• Domain renewals

  Need to know how hoe to renew the domain

• MX shopify problem

  hello, i added all MX values in my shopify DNS - it shows those values on the shopify panel + your toolkit. I tried to send some email and it works, however on my gmail it says they cant verify this email. When i try to answer into my domain's email -

• Best Way to Manage Email Notifications While Running a Strategy Website

  I am currently managing a content-based website, and I use Zoho Mail for handling contact forms, user queries, and collaboration emails. One challenge I am facing is organizing incoming emails efficiently, especially when messages come from different

• What is the maximum email domains ?

  I help manage about 20 associations and I'm looking for a way to centralize them in one place. Does Zoho Mail pro or enterprise support 20-30 domains for 3-5 users each?

• Add to Workdrive filter

  I'm trying to create a filter that will upload attachments in emails and the e-mail body to a folder in workdrive. I am able to do one or the other (attachment, or e-mail content), but not both. I first tried it using the "Email (EML) + attachment" option.

• Forgot my admin Panel Id and password

  Sir, I have an account , where a domain mycityestate.in is added for Zoho email , now it is hard for me to manage email because i have forgotten the Email account and password registered with Admin Panel of Zoho. Just need email name which is registered

• MCP no longer works with Claude

  Anyone else notice Zoho MCP no longer works with Claude? I'm unable to turn this on in the claude chat. When I try to toggle it on, it just does nothing at all. I've tried in incognito, new browsers, etc. - nothing seems to work.

• Image Compression Options

  Much better if we have level of options to compress the image [20%, 40%...] We are dealing with service reports daily that has before and after photos (image field)- the file size too large and one thing, the current limit is 10mb or 15mb for report

• WhatsApp IM in Zoho Desk always routes to Admin instead of assigned agent

  Hello Zoho Experts, I connected WhatsApp IM to my Zoho Desk account. I only assigned my Customer Service (CS) agent to the WhatsApp channel, and I did NOT include Admin in this channel. However, every new WhatsApp conversation automatically gets assigned

• Zoho CRM || Unable to Bulk Assignment of Territories for Contacts

  Dear Zoho CRM Support Team, I hope this email finds you well. We recently performed a bulk upload of Contacts into Zoho CRM using the official sample Excel template downloaded from the CRM. The upload itself was completed successfully; however, we encountered

• Blocklist candidates in Zoho Recruit

  We’re introducing Block Candidate, which helps recruiters to permanently restrict a candidate from applying to current/future job openings. Once the candidate is blocked, they will no longer be able to participate in the recruitment process. This will

• Pass shipping info to payment gateway Zoho Books to Authorize.net

  For some reason the integration from Zoho books to Authorize.net does not pass the shipping address. Authorize.net is ready to receive it, but zoho books does not send it

• Knowledgebase SEO

  We have a custom-domain mapped help center that is not restricted via login. I have some questions: a) will a robots.txt file still allow us to control indexing? b) do we have the ability to edit the sitemap? c) do category URLs get indexed by search

• Power Pivot and Data Modeling functionality in Zoho Sheet

  When will MS Excel functionalities like Power Pivot and Data Modeling functionalities be available in Zoho Sheet?

• Problem with CRM Connection not Refreshing Token

  I've setup a connection with Zoom in the CRM. I'm using this connection to automate some registrations, so my team doesn't have to manually create them in both the CRM and Zoom. Connection works great in my function until the token expires. It does not refresh and I have to manually revoke the connection and connect it again. I've chatted with Zoho about this and after emailing me that it couldn't be done I asked for specifics on why and they responded. "The connection is CRM is not a feature to

• Next Page