How to get layout fields in Zoho Desk

Retrieving layout fields in Zoho Desk is straightforward once you have a valid layoutId and the correct OAuth scopes in place — a single GET request returns all fields associated with that layout.

Why this matters

When building integrations or automations on top of Zoho Desk, you often need to know exactly which fields exist on a given ticket or contact layout before you can map data, validate submissions, or render dynamic forms. Fetching layout fields programmatically lets your code stay in sync with whatever configuration your Desk administrators have set up, without hard-coding field names. This is also the right starting point before attempting to reposition or update fields on a layout.

Step-by-step

Step 1. Confirm your OAuth token includes the necessary Desk scopes. At minimum you will need Desk.settings.READ to access layout configuration endpoints. A broader set of settings scopes — including Desk.settings.ALL — is commonly configured to cover read and write operations across Desk settings. ^[6]

Step 2. Identify the layoutId you want to inspect. Layout IDs are unique identifiers assigned to each ticket, contact, or account layout in your Desk portal. If you do not already have the ID, you can retrieve it from your Desk admin panel under Setup → Layouts, or by querying the layouts list endpoint first.

Step 3. Send a GET request to the layout fields endpoint. The path follows this pattern:

GET /api/v1/layouts/{layoutId}/fields

Replace {layoutId} with the actual ID of your target layout. The endpoint also accepts an optional p parameter for pagination or filtering purposes. ^[1]

Step 4. In Python, the call looks like this:

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

Pass your layout ID as a string, and supply a dictionary for p if you need to control pagination or apply query parameters. If no extra parameters are needed, p can be omitted or passed as None. ^[1]

Step 5. Parse the response. The API returns a structured list of field objects for the specified layout. Each object typically includes field names, types, and configuration metadata that you can use to drive downstream logic in your integration.

Step 6. If you also need to understand how fields are grouped visually, complement this call with the layout sections endpoint:

GET /api/v1/layouts/{layoutId}/sections

This returns the section structure of the layout, which is useful when you need to render a form that mirrors the Desk UI. ^[7]

Step 7. If your use case requires repositioning fields after retrieving them, use the PATCH variant of the same path:

PATCH /api/v1/layouts/{layoutId}/fields

This operation accepts a data payload describing the new field positions. ^[8]

Common pitfalls

• Wrong scope. If your OAuth token was generated without Desk.settings.READ (or Desk.settings.ALL), the API will return an authorisation error. Double-check the scopes list in your OAuth configuration before debugging the request itself. ^[6]

• Mixing up Desk and CRM layout endpoints. Zoho CRM uses a different base path — /settings/layouts/{lid} with a module parameter — which is entirely separate from the Desk layout fields endpoint. Make sure you are targeting /api/v1/layouts/{layoutId}/fields for Desk, not the CRM equivalent. ^[1][4]

• Missing or incorrect layoutId. Passing an invalid or mismatched layout ID will result in a 404 or empty response. Always verify the ID belongs to the correct department and layout type (ticket vs. contact vs. account) before making the call.

• Pagination not handled. If a layout has a large number of fields, the response may be paginated. Use the p parameter to iterate through pages and ensure you collect the complete field list. ^[1]

What to check

• Scopes are active: Verify that Desk.settings.READ or Desk.settings.ALL appears in your token's granted scopes before making the request. ^[6]
• Correct endpoint base URL: Confirm you are calling the Zoho Desk API base (e.g., https://desk.zoho.com) and not a CRM or other Zoho product URL. ^[3]
• Response completeness: If the field count seems lower than expected, check whether pagination is truncating results and re-query with the appropriate p parameter. ^[1]

---

*Beam Help provides independent expert support for Zoho products and is not official Zoho support. Always refer to Zoho's own documentation for the most current API specifications.*