Kaizen #197: Frequently Asked Questions on GraphQL APIs

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. 

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?

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.

    • Recent Topics

    • Zoho Desk - Custom Module Related List Columns on Tickets

      I have a custom module in Zoho Desk called Asana Tasks, each task has a lookup to a Ticket. On the Ticket I want to see the columns of the Asana Tasks in the related list . Is there a way to do this? Right now it just has the name of the record and I

    • Why is Zoho Meeting quality so poor?

      I've just moved from Office 365 to Zoho Workplace and have been generally really positive about the new platform -- nicely integrated, nice GUI, good and easy-to-understand control and customisation, and at a reasonable price. However, what is going on

    • Creator HTML page refresh

      Hi, I have added around 5 different html snippets in single creator page. I understand, I can refresh the entire page from page script using Navigational URLs https://help.zoho.com/portal/en/kb/creator/developer-guide/others/url-patterns/articles/navigational-urls

    • Google Analytics import data inaccurate (as of October 11, 2025)

      We have Zoho Analytics connected to GA4 to import daily event data. This has been running without issue for a couple of years. However, a month ago we started noticing discrepancies. All data until October 10 lines up perfectly - October 11 onward is

    • Paid Support Plans with Automated Billing

      We (like many others, I'm sure) are designing or have paid support plans. Our design involves a given number of support hours in each plan. Here are my questions: 1) Are there any plans to add time-based plans in the Zoho Desk Support Plans feature? The

    • What is your opinion of the new UI?

      Hi Everyone, I would like to see what everyone thinks of the new Zoho One Dashboard. I don't get it, but perhaps I'm missing something. What are your thoughts?

    • What are the OAuth scopes needed to access the Zoho MCP server?

      I think I'm authenticating with the MCP server endpoint successfully using a bearer token but I can't successfully initialize an MCP session. I'm using the official MCP Python sdk (https://github.com/modelcontextprotocol/python-sdk). I get as far as here

    • Support Uploading YouTube Videos Longer Than 60 Minutes

      Hi Zoho Social Team, How are you? We would like to request support for uploading YouTube videos longer than 60 minutes directly through Zoho Social. Your support team informed us that Zoho Social currently cannot upload videos over 60 minutes due to “API

    • Account blocked for IMAP use

      Hello, My email client (Evolution) can't sync mail anymore. It gives the error: "Your account is temporarily blocked for IMAP use. This may happen if you exceed the maximum number of simultaneous IMAP connections allowed. Kindly try again after some time."

    • Is SMTP included in the free plan?

      My client has a Zoho Mail Free 14 day trial that ends tomorrow. She has set up a domain email address with SMTP on a third party app and is wondering if it will continue working once her plan downgrades to the free forever plan. Thanks

    • Zoho mail issue.

      I have verified my domain ohhoexpress.online by adding necessary TXT and MX records. But when I am sending email to any external email id, it is showing as zohomail.com. Also while I am sending mail to internal mail id, it is saying user not found whereas

    • My email is blocked from sending

      I get this message when I try to send any message .. > Unable to send message, Reason 554 5.1.8 Email Outgoing Blocked We have urgent emails to send and the issue continues to persist from yesterday. Please help us with this issue as soon as possibl

    • [WEBINAR] Smooth year-end closure with Zoho Books (KENYA)

      Hello there, This webinar is for all Kenyan businesses looking to wrap up their financial year smoothly! Join our free session to learn how Zoho Books can simplify your year-end process. What to expect from this webinar: - All the latest updates in Zoho

    • cannot recieve or send emails

      we are not recieving or cannot send emails.Shows sysytem error

    • Getting Attachments in Zoho Desk via API

      Is there a way to get attachments into Zoho Desk via an API?      We have a process by which a zoho survey gets sent to the user as a link in a notification.    The survey has several upload fields where they can upload pdf documents.    I've created

    • Zoho Sites - contact us form

      I have added a contact us form to my website. I wanted to change the layout so I deleted the section of Contact Us form. When I again try to add the section of Contact Us form, it shows error that "This form already exists on this page."  I am unable

    • Setting checkbox value on template in Sign from Creator

      Good day, Please help me understand how do I set a tick from a checkbox in Creator into a checkbox on a Sign template. Below is the only values on the Sign template and the code from Creator, "field_boolean_data": {}, "field_date_data": {}, "field_radio_data":

    • Scheduled Reports - Do not send empty report

      Hello, We are intensively using reports in the CRM, especially for sales managers.  When data is empty, they still receive an email. Can you add an option to avoid sending the report when data is empty?

    • Zoho Forms - Improve the CRM integration field to query data from more than one module

      Hi Forms team, Something I get stuck on regularly is pre-populating a form with data when that data is spread across 2 or 3 modules. For example Contacts, Accounts and Deals. I don't want to duplicate the information in CRM so I end up writing a function

    • Ask the Experts 25: Experience the full spectrum of Zoho Desk’s autumn and spring releases for 2025

      Hello Everyone, We’re on the 25th episode of our ATE series! It's a true milestone in our live community interactions! It’s been an amazing journey since we started in October 2018. Zoho Desk has come a long way, evolving with the support of a wonderful

    • switching from POP3 to IMAPI do I need to change settings in Web email?

      hi so I am using Outlook with My Zoho mail, also have Verizon email /AOL. they no longer support POP3 and said imapi is much better, so I want to switch my ZoHo to imapai. I googled and it said i need to change it in my account....i looked at my account

    • Can multiple agents be assigned to one ticket on purpose?

      Is it possible to assign one ticket to two or more agents at a time? I would like the option to have multiple people working on one ticket so that the same ticket is viewable for those agents on their list of pending tickets. Is something like this currently

    • What functionality is new in the Z025 Spaces UI dashboard compared to the previous Zoho One dashboard?

      My company is interested in creating a revamped dashboard this coming year, and are trying to weigh different platform options. The new Spaces UI is said to be a more "feature-rich" dashboard experience than the previous. Could a developer please explain

    • Collections Management: #5 Convenience on Offer, using Self-Checkout

      "Is this the right page? Oh, now, it wants my address again. Why am I being redirected?" These were the exact thoughts running through Karan's mind as he tried to subscribe to an application he genuinely liked. He clicked "Buy Now", expecting a quick

    • Uploading a signed template from Sign to Creator

      Good day, Please help me on how to load a signed document back into Creator after the process has been completed in Sign. Below is the code that I am trying, pdfFile = response.toFile("SignedDocument_4901354000000372029.pdf"); info pdfFile; // Attach

    • Tip #50- A Closer Look at the Unattended Access Dashboard- 'Insider Insights'

      Having complete visibility and quick access to everything you need certainly makes managing multiple remote devices a lot easier, and that is precisely what the Unattended Access Dashboard in Zoho Assist is designed to offer. Once you go to the Unattended

    • Zoho CRM Portal User Timeline History Unavailable

      Hi Support Team, We have noticed a feature limitation in the Zoho CRM portal. We created a portal for our vendors to edit records directly, but when vendors make updates, the Modified Time and Date fields are not being updated. Additionally, these updates

    • New in Smart Prompt: Record Assistant for contextual assistance, and support for new AI models

      Smart Prompt helps teams stay informed and move faster by providing relevant suggestions where work happens in CRM. With this update, Smart Prompt becomes more adaptable to your organization’s AI preferences. You can now choose which Large Language Model

    • Almost all Flows are being queued

      A few days ago I saw one of my Flows status was Queued. This was the first time this had ever happened. Now, almost every Flow that triggers is Queued for at least a few minutes. If I re-trigger the Flow (which causes separate problems) they sometimes

    • Zoho Map integration tasks have changed - you need to "Locate all instances of Zoho Map integration tasks in your Deluge scripts by searching for the v1 marker... before 16 January 2026"

      Details of an issue specific to Zoho CRM + Deluge Functions (originally posted in this forum) can be found here: https://help.zoho.com/portal/en/community/topic/zoho-map-integration-tasks-have-changed-you-need-to-locate-all-instances-of-zoho-map-integration-tasks-in-your-deluge-scripts-by-searching-for-the-v1-marker

    • How to update custom multi-user field in Zoho Projects?

      I'm trying to update custom multi-user fields in Zoho Projects via a Deluge function in CRM. The code I have so far is below. It works for updating standard project fields and single-line custom fields, but it does not work to update multi-user fields.

    • Tip of the Week #75– Manage your social media messages from a single shared inbox.

      Are you tired of jumping between apps or browser tabs to reply to your business's Facebook and Instagram DMs? Handling customer messages on social media might seem simple, but switching between multiple platforms can easily lead to lost messages, duplicate

    • Zoho Map integration tasks have changed - you need to "Locate all instances of Zoho Map integration tasks in your Deluge scripts by searching for the v1 marker... before 16 January 2026"

      The Zoho Map deluge integration task has been changed (as at 21 October 2025) to provide a more structured, JSON-like response. This change affects all three Zoho Map integration tasks (Geocode, Reverse Geocode, and Distance Between). More details can

    • Using files from Zoho CRM in Gemini/ChatGPT/Claude

      Hi all, I’ve got subscriptions to Gemini and a few other AI tools which I use for tasks like data enrichment, email composition, etc. In our workflow, we often receive various documents from clients — such as process workflows, BRDs/requirement documents

    • Zoho Analytics & Zoho Creator - Modified Time value

      I'm trying to use the Zoho Creator system field 'modified time' in Zoho Analytics, but it's consistently showing 12 hours 'out' In Zoho Creator In Zoho Analytics Is this a constant difference that I just need to correct with a timezone change - or is

    • Zoho CRM - Option to create Follow-Up Task

      When completing a Zoho CRM Task, it would be very helpful if there was an option to "Complete and Create Follow-Up Task" in the pop-up which appears. It could clone the task you are closing and then show it on the screen in edit mode, all the user would

    • Portal For Different Apps

      I found some older threads on this but didn't see anything very recent. I'm new to Zoho One so forgive me if my terminology is off a bit. I was hoping set up a single point of entry into Zoho One. So, many of the apps could be found in one single place

    • Calls undetected

      Zoho Voice records indicate my last call ended at 6:00 PM. All incoming and outgoing calls occurred between 6:00 PM and 7:00 PM.

    • Send Zoho Forms Link using Zoho CRM Email Templates

      I have set up Zoho Forms and CRM integration to pre-populate data from Zoho CRM to Zoho Forms. The setup is working fine. I have also created an email template in the Zoho CRM deals module to send Zoho forms links. So when I send an email using that template

    • Zoho Projects - Project Details on the Project Menu

      Hi Project's team, I've helped may businesses setup and use Zoho Project and one thing I see time and time again is confusion on where to find the Project Details information. I would be much more intuitive if Project Details was on the menu before Dashboard.

    • Next Page