How to retrieve records in Zoho CRM

Zoho CRM's GraphQL API lets you fetch both record data and metadata from your CRM modules in a single, flexible query — making it a powerful alternative to traditional REST calls when you need to pull from multiple modules at once.

Why this matters

When building integrations, dashboards, or custom widgets, developers often need to retrieve data from several Zoho CRM modules simultaneously. The GraphQL API addresses this by allowing you to combine Records and Meta queries in one request, reducing round-trips and giving you precise control over which fields are returned. ^[1] This is especially useful for teams building reporting tools or syncing CRM data with external systems.

Step-by-step

Step 1. Confirm your Zoho CRM edition supports GraphQL. The GraphQL API is unavailable on trial versions of any Zoho CRM edition, so you must be on a paid plan before proceeding. ^[1]

Step 2. Authenticate your API client. You will need a valid OAuth 2.0 access token scoped to Zoho CRM before sending any GraphQL request. Once you have your token, set it as a Bearer token in the Authorization header of your HTTP request. ^[1]

Step 3. Understand the two root query types available to you. The GraphQL schema exposes a root Query type with two main branches: ^[1]

• Records — retrieves actual data rows from any CRM module your profile can access. Filtering and pagination are supported across all modules.
• Meta — retrieves structural/configuration data from sources such as Modules, Users, KanbanView, UserProperties, ProfilePermissions, Profiles, Roles, and Widgets. Some of these support filtering and pagination as well.

Step 4. Construct your GraphQL query. Below is an example that pulls AccountName from the Accounts module, LastName from Leads, apiname from Roles, and lastname from Users — all in a single request: ^[1]

query {
    Records {
        Accounts {
            _data {
                Account_Name {
                    value
                }
            }
        }
        Leads {
            _data {
                Last_Name {
                    value
                }
            }
        }
    }
    Meta {
        Roles {
            _data {
                api_name
            }
        }
        Users {
            _data {
                last_name
            }
        }
    }
}

Notice that record field values are accessed via the value key nested under each field name, while certain metadata fields (like api_name) are accessed directly. ^[1]

Step 5. Send the query to the Zoho CRM GraphQL endpoint using your preferred HTTP client (e.g., curl, Postman, or a server-side SDK). Include your OAuth token in the request header and set the Content-Type to application/json. ^[1]

Step 6. Parse the response. The API returns a structured JSON object mirroring the shape of your query. Records appear under _data arrays within each module node, and metadata fields appear under their respective type nodes. ^[1]

Common pitfalls

• Trial account restriction. Attempting to use the GraphQL API on a Zoho CRM trial will result in an error. You must upgrade to a paid edition first. ^[1]
• Profile-based access. The Records query only surfaces modules and fields that your CRM profile has permission to view. If a module appears empty or is missing from the response, check your profile's field-level and module-level permissions in Zoho CRM. ^[1]
• Field name case sensitivity. GraphQL queries in Zoho CRM are case-sensitive. For example, LastName and lastname refer to different fields in different contexts (Records vs. Meta). Double-check the exact API names of your fields before querying. ^[1]
• Pagination for large datasets. While filtering and pagination are supported for all Records modules and some Meta types, omitting pagination arguments on large modules may result in truncated responses. Always implement pagination when querying modules with high record volumes. ^[1]

What to check

• Edition and trial status — verify your org is on a paid Zoho CRM plan, since GraphQL is blocked on trial accounts. ^[1]
• OAuth token scope — confirm your access token includes the correct CRM scopes; an under-scoped token will cause authentication failures even if the query syntax is correct. ^[1]
• Field API names — cross-reference the field names used in your query against the actual API names in your CRM setup (found under Setup → Modules and Fields) to avoid empty or error responses. ^[1]

---

*Beam Help is an independent expert support resource for Zoho products and is not official Zoho support. For platform-level issues, always verify with Zoho's official documentation or support channels.*