How to get layout details in Zoho Desk

Retrieving layout details in Zoho Desk is done via a single authenticated GET request to the layouts endpoint, passing the target layout's ID as a path parameter.

Why this matters

Layouts in Zoho Desk control which fields appear on tickets, contacts, and other records — and in what order. If you are building an integration, automating field validation, or auditing your Desk configuration, you need programmatic access to layout metadata. This endpoint lets you inspect a specific layout's structure without navigating the Desk admin UI manually.

> Note: Beam Help is independent expert support for Zoho — we are not official Zoho support.

---

Step-by-step

Step 1. Ensure your OAuth token includes the correct Zoho Desk scopes before making any API call. At minimum, your token should cover Desk.settings.READ so the layouts endpoint will accept the request. ^[3]

Step 2. Identify the layoutId you want to inspect. You can find this value in the Zoho Desk admin panel under the layout settings, or by first calling the list-layouts endpoint to enumerate all available layouts and capturing the ID from the response.

Step 3. Send a GET request to the layouts detail endpoint, substituting your target ID into the path:

GET /api/v1/layouts/{layoutId}

The optional query parameter p can be included if you need to pass additional pagination or filter hints alongside the request. ^[1]

Step 4. In Python, the call looks like this — pass the layoutId as a string, and supply an optional dictionary for any extra query parameters:

def get_layout_details(self, layoutId: str, p: dict = None):
    return self.c.request("GET", f"/api/v1/layouts/{layoutId}", p, None)

The method forwards the request through your configured HTTP client, which should already hold a valid Bearer token. ^[1]

Step 5. Parse the JSON response body. The returned object will contain the field definitions, section groupings, and metadata associated with that specific layout. Store or log what you need before making further calls.

---

Common pitfalls

• Wrong scope granted. If your OAuth client was configured without Desk.settings.READ (or the broader Desk.settings.ALL), the API will return an authorisation error. Double-check the full scope list in your environment configuration — the settings family of scopes is separate from tickets, contacts, and tasks scopes. ^[3]

• Mixing up Desk and CRM layout endpoints. Zoho CRM has its own layout API at GET /settings/layouts/{lid} which also requires a module parameter. ^[4] These two endpoints are entirely separate — using the CRM path against a Desk layout ID (or vice versa) will not return useful data. Make sure you are targeting /api/v1/layouts/{layoutId} for Desk work. ^[1]

• Missing or malformed layoutId. The layoutId must be passed as a path segment, not a query parameter. Passing it incorrectly will either hit the wrong route or return a 404.

---

What to check

• Scope coverage: Confirm your active OAuth token includes Desk.settings.READ or Desk.settings.ALL before the request is sent. ^[3]
• Correct endpoint version: Verify you are calling /api/v1/layouts/{layoutId} (the Zoho Desk v1 API) and not the Zoho CRM settings/layouts path. ^{[1] [4]}
• Valid layout ID in the path: Confirm the layoutId value exists in your Desk organisation by cross-referencing it against the layout list before relying on the response data.