How to list layouts in Zoho Desk

Listing layouts in Zoho Desk via the API is straightforward once your OAuth connection is configured with the correct scopes and your organisation credentials are in place.

Why this matters

When building integrations or automations against Zoho Desk, you often need to know which layouts exist for a given department so you can map fields correctly or route tickets to the right form. Retrieving the layout list programmatically lets your code stay in sync with whatever an administrator has configured in the Desk portal, without manual look-ups.

Step-by-step

Step 1. Confirm your OAuth scopes include settings access.

Before any layout-related API call will succeed, your Zoho Desk OAuth token must include the Desk.settings.READ scope (at minimum). A full settings scope set looks like Desk.settings.ALL, Desk.settings.READ, Desk.settings.WRITE, Desk.settings.CREATE, Desk.settings.UPDATE, and Desk.settings.DELETE. Without at least the READ variant, the API will return an authorisation error. ^[4]

Step 2. Identify your organisation ID and portal name.

Every Zoho Desk API call is scoped to an organisation. Your deskorgid is discovered automatically when the connection is first established — the system queries the organisations endpoint, reads the first item's id field, and stores it against your connection record. ^[7] You will also need your portal slug (desk_portal), which appears in your Desk agent URL in the format https://desk.zoho.{dc}/agent/{portal}/. ^[3]

Step 3. Construct the base URL for your data centre.

Zoho Desk is hosted across multiple data centres. For the .com region the agent root is https://desk.zoho.com/agent; for any other region substitute the appropriate suffix, e.g. https://desk.zoho.eu/agent. Append your portal slug or org ID to form the full base: https://desk.zoho.{dc}/agent/{portal}. ^[3]

Step 4. Call the Layouts endpoint.

With your base URL and a valid access token in hand, make a GET request to the layouts resource under the relevant department. The canonical Zoho Desk API path follows the pattern:

GET https://desk.zoho.{dc}/api/v1/departments/{departmentId}/layouts

Pass your access token as a Bearer token in the Authorization header. The response will contain an array of layout objects, each with an id, name, and associated field metadata.

Step 5. Handle the response and build navigation links.

Once you receive the layout list, store or display the id and name pairs. If you are surfacing these results in a UI, you can construct direct agent links using the same base URL pattern — https://desk.zoho.{dc}/agent/{portal}/ — and append the relevant path for the record type (tickets, contacts, accounts, etc.). ^{[1] [3]}

Step 6. Verify the correct scopes are active end-to-end.

As a final check, confirm that Desk.basic.READ is also present in your token, since department and agent metadata (which layouts are tied to) falls under the "basic" scope group. ^[4]

---

> Note: Beam Help is independent expert support for Zoho — we are not official Zoho support. For billing or account-level issues, contact Zoho directly.

---

Common pitfalls

• Missing Desk.settings.READ scope. This is the most frequent cause of a 403 response when querying layout endpoints. Double-check your OAuth scope string includes it. ^[4]
• Wrong data centre suffix. If your portal is on the EU or AU region and you use .com in the base URL, requests will fail silently or return a redirect. Always derive the base URL from the dc value stored with your connection. ^[3]
• Org ID not yet discovered. If the connection was created but never used to make a live API call, the deskorgid field may still be empty. Trigger a lightweight read (e.g., list tickets) first so the system can auto-populate the org ID from the organisations endpoint response. ^[7]

---

What to check

• Confirm your active OAuth token includes both Desk.settings.READ and Desk.basic.READ before calling the layouts endpoint. ^[4]
• Verify that deskorgid and desk_portal are both populated in your connection record, since both are needed to build a valid request URL. ^{[3] [7]}
• After retrieving layouts, cross-reference at least one returned layout id against your Zoho Desk admin panel (Setup → Layouts) to confirm the API response matches what is live in the portal. ^[3]