How to retrieve layouts in Zoho CRM

Retrieving layouts in Zoho CRM is most commonly done through the Zoho CRM API, which lets you pull layout metadata — including field arrangements and section structures — for any module in your account. Here at Beam Help (independent expert support for Zoho, not official Zoho support), we walk you through the key approaches below.

Why this matters

When you're building integrations, custom UIs, or automations, you often need to know exactly how a module's page layout is structured before you can render or validate data correctly. Layouts define which fields appear, in what order, and under which sections — so fetching them programmatically is a foundational step for any serious Zoho CRM development project. This is also relevant when you want to audit layout differences across profiles or sync layout changes to an external system. ^[3]

---

Step-by-step

Step 1. Confirm your Zoho CRM edition supports API access. GraphQL APIs, for example, are not available in trial versions of any Zoho CRM edition, so make sure your account is on a paid plan before attempting metadata retrieval. ^[3]

Step 2. Decide which API surface fits your use case. Zoho CRM offers both REST-style endpoints and a GraphQL API. The GraphQL API is particularly well-suited for layout and metadata retrieval because it exposes a dedicated Meta root type that covers modules, users, profiles, roles, and related metadata in a single query. ^[3]

Step 3. Authenticate your application using OAuth 2.0 to obtain a valid access token. All Zoho CRM API calls require a bearer token scoped to the appropriate CRM permissions. Refer to the Zoho CRM developer documentation for the correct OAuth scopes for metadata access.

Step 4. To retrieve layout metadata via the GraphQL API, send a query targeting the Meta type. The Meta type supports retrieval from Modules, Users, KanbanView, UserProperties, ProfilePermissions, Profiles, Roles, and Widgets. Some of these types also support filtering and pagination, which is useful when you only need layouts for a specific module. ^[3]

A minimal GraphQL query targeting module metadata looks like this:

query {
  Meta {
    Modules {
      _data {
        api_name
      }
    }
  }
}

Extend the _data block with the layout-specific fields your integration requires (such as layout ID, name, or associated profiles). ^[3]

Step 5. If you are working within a browser-based widget or client-side application, consider using the Zoho CRM JavaScript SDK rather than raw HTTP calls. The SDK provides a structured way to make API calls from within Zoho CRM's UI context, and sample code for fetching module data is available in the SDK's GitHub repository. ^[5]

Step 6. Once you have retrieved layout data, cross-reference it with what you see in the Zoho CRM UI by navigating to Setup → Modules and Fields. This is the same area where module and layout customisation is managed, and it serves as a useful sanity check that your API response matches the live configuration. ^{[1] [2]}

Step 7. If your project involves Canvas-based layouts (custom record detail views), be aware that Canvas now supports views for record creation pages in addition to detail views. Canvas views can also be exported and imported across CRM accounts using a unique key, which is valid for a limited period. If you need to replicate layouts across organisations, this export/import mechanism may complement your API-based retrieval workflow. ^[8]

---

Common pitfalls

• Trial account restrictions. Attempting GraphQL metadata queries on a trial Zoho CRM account will fail. Upgrade to a paid edition before testing. ^[3]
• Scope mismatches. If your OAuth token lacks the correct CRM metadata scope, the API will return an authorisation error rather than layout data. Always verify your token's scopes match the endpoint you're calling.
• GraphQL vs REST confusion. The Meta type and its sub-types (including Modules) are specific to the GraphQL API. If you are using the REST API, the endpoint structure and response format differ significantly. Mixing up the two is a common source of unexpected errors. ^[3]
• Canvas layouts are separate. Standard page layouts and Canvas views are distinct constructs in Zoho CRM. The API metadata for a module's standard layout will not automatically include Canvas template details. ^[8]

---

What to check

• Verify the API response includes the expected module api_name values and that they match the module names visible under Setup → Modules and Fields in your CRM account. ^{[1] [3]}
• Confirm pagination is handled if your CRM has a large number of modules or layouts — the GraphQL Meta type supports pagination for some sub-types, and truncated responses are a common silent failure. ^[3]
• Test with the JavaScript SDK if your integration runs inside a Zoho CRM widget, to ensure the correct authentication context is used rather than a manually managed OAuth token. ^[5]