How to retrieve roles in Zoho CRM

Roles metadata in Zoho CRM can be retrieved programmatically using the GraphQL API by querying the Meta type and specifying the Roles object along with the fields you need.

Why this matters

When building integrations or admin tooling on top of Zoho CRM, you often need a list of all configured roles — for example, to map users to their hierarchy, validate access levels, or populate a dropdown in an external app. The GraphQL API gives you a structured, flexible way to pull this metadata in a single request alongside other organisational data such as Users or Profiles. As independent expert support for Zoho (not official Zoho support), Beam Help recommends this approach for any developer needing programmatic role discovery.

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. Understand the query structure. Zoho CRM's GraphQL API exposes two root types: Meta (for organisational metadata such as Modules, Users, Profiles, and Roles) and Records (for module data). To fetch roles, you will be working entirely within the Meta type.^[1]

Step 3. Construct your GraphQL query. Place Roles inside the Meta block, then specify data and the fields you want returned — for example, apiname. A minimal query looks like this:

query {
    Meta {
        Roles {
            _data {
                api_name
            }
        }
    }
}

This asks Zoho CRM to return the api_name field for every role defined in your organisation.^[1]

Step 4. Combine with other metadata if needed. Because Meta supports multiple types in a single request, you can retrieve roles and users together in one round-trip. For example, adding a Users block alongside Roles lets you correlate role names with user last names without making separate calls.^[1]

query {
    Meta {
        Roles {
            _data {
                api_name
            }
        }
        Users {
            _data {
                last_name
            }
        }
    }
}

Step 5. Send the query to the Zoho CRM GraphQL endpoint using your preferred HTTP client, passing a valid OAuth 2.0 access token in the Authorization header. The response will contain a structured JSON object with your role data nested under Meta > Roles > _data.^[1]

Common pitfalls

• Trial accounts are blocked. If your organisation is on a trial of any Zoho CRM edition, the GraphQL API will not be accessible. You must upgrade to a paid tier before these queries will work.^[1]
• Requesting non-existent fields. The data block only accepts fields that are valid for the Roles type (such as apiname). Requesting an undefined field will cause the query to fail. Check the GraphQL schema introspection to confirm available fields before building your query.^[1]
• Mixing up Meta and Records. Role information is metadata, not a module record. Placing Roles inside the Records block instead of Meta will produce an error. Always use Meta for organisational constructs like Roles, Profiles, and Users.^[1]

What to check

• Edition eligibility: Verify your Zoho CRM account is on a paid plan and that GraphQL API access has not been restricted by your administrator.
• Field accuracy: Confirm that the fields you request inside data (e.g., apiname) are valid for the Roles type by running a schema introspection query first.^[1]
• Response structure: After executing the query, ensure the returned JSON contains data under the Meta > Roles > _data path and that the number of roles matches what you see in your CRM's role hierarchy settings.^[1]