How to list criteria fields for layout rules in Zoho Desk

Listing the criteria fields available for layout rules in Zoho Desk is done through a single GET request that returns the fields you can use when building rule conditions. Here at Beam Help — independent expert support for Zoho (not official Zoho support) — we walk you through exactly how to call this endpoint and what to watch for.

Why this matters

Layout rules in Zoho Desk let you show, hide, or mandate fields based on conditions set at the ticket or record level. Before you can build those conditions, you need to know which fields are eligible as criteria. Fetching this list programmatically saves time and ensures your rule definitions reference only valid, supported fields. This is especially useful when automating Desk configuration or auditing existing layout rules across departments.

Step-by-step

Step 1. Confirm your OAuth token includes the correct Zoho Desk scopes. At minimum you will need Desk.settings.READ in your active token, since criteria-field lookups fall under the settings surface of the API. A broader configuration also includes Desk.settings.ALL for full read/write access to settings resources. ^[3]

Step 2. Send a GET request to the layout-rules criteria-fields endpoint:

GET /api/v1/layoutRules/criteriaFields

Pass any relevant query parameters in the p dictionary (for example, department or layout identifiers if your integration requires scoping). The operation name for this call is listcriteriafields. ^[8]

Step 3. In your Python client, invoke the method as shown below:

result = desk_client.list_criteria_fields(p={"departmentId": "<your_dept_id>"})

The underlying request is a standard authenticated GET with the parameter dictionary forwarded as query-string arguments. ^[8]

Step 4. Parse the response payload. Each item in the returned collection represents a field that can be used as a criterion inside a layout rule. Note the field API names carefully — you will need them verbatim when you subsequently create or update layout rules via GET /api/v1/layoutRules. ^[5]

Step 5. If you are working with validation rules rather than layout rules, the criteria-fields endpoint is slightly different:

GET /api/v1/validationRules/criteriaFields

The operation name is listcriteriafieldsforlayout, and it targets validation-rule criteria specifically rather than layout-rule criteria. Use the correct endpoint for your use case to avoid receiving an irrelevant field list. ^[2]

Step 6. Cross-reference the fields returned against your existing layout rules by calling:

GET /api/v1/layoutRules

This listlayoutrules operation returns all configured layout rules, letting you verify which criteria fields are already in use and which are available for new conditions. ^[5]

Common pitfalls

• Wrong endpoint for validation vs. layout rules. The path /api/v1/layoutRules/criteriaFields is for layout rules ^[8], while /api/v1/validationRules/criteriaFields is for validation rules ^[2]. Mixing them up returns a valid 200 response but with fields scoped to the wrong rule type, which can cause silent mismatches when you build conditions.

• Missing or under-scoped OAuth token. If your token was generated without Desk.settings.READ or Desk.settings.ALL, the API will return an authorisation error. Review the full scope list and regenerate your token if needed. ^[3]

• No department filter applied. Zoho Desk is department-aware. If you omit a department identifier in your query parameters, the response may return a global field list that does not reflect department-specific custom fields. Always pass the relevant department context when your portal uses multiple departments.

What to check

• Scope coverage: Verify your active OAuth token contains at least Desk.settings.READ before making the call. ^[3]
• Correct endpoint path: Confirm you are hitting /api/v1/layoutRules/criteriaFields for layout rules and /api/v1/validationRules/criteriaFields for validation rules — do not interchange them. ^[2][8]
• Field name accuracy: After retrieving the list, ensure any field API names you copy into rule conditions exactly match what the endpoint returned, as layout rules will reject unrecognised field identifiers. ^[5]