How to get field permissions in Zoho Desk

Retrieving field-level permissions in Zoho Desk is done through a single GET request to the organisation fields endpoint, supplying the target module name and field ID as path parameters.

Why this matters

Field permissions control which agents or profiles can view or edit specific fields on records such as tickets, contacts, and accounts. If you are auditing your Zoho Desk configuration, building an integration, or troubleshooting why certain fields are hidden for a profile, you will need to query these permissions programmatically. Understanding the correct endpoint and required OAuth scopes saves significant debugging time.

> Beam Help is independent expert support for Zoho — not official Zoho support.

---

Step-by-step

Step 1. Confirm your OAuth token includes the right scopes before making any call. For field-permission reads you need at minimum Desk.settings.READ in your authorised scope set. A broader configuration also includes Desk.settings.ALL, Desk.settings.WRITE, and related variants if you intend to update permissions later. ^[3]

Step 2. Obtain a valid Zoho Desk API client instance. The client must be initialised with your API domain, a current access token, and your organisation ID. If the organisation ID is not yet stored, the client can auto-discover it by calling the organisations list endpoint and persisting the first result. ^[7]

Step 3. Identify the two required path parameters:

• moduleName — the Desk module whose field you are inspecting (for example, tickets, contacts, or accounts).
• fieldId — the unique identifier of the specific organisation field whose permissions you want to retrieve. ^[2]

Step 4. Send a GET request to the following endpoint, substituting your values for {moduleName} and {fieldId}:

GET /api/v1/organizationFields/{moduleName}/{fieldId}/permissions

An optional query-parameter dictionary (p) can be passed to filter or paginate the response if the API supports it. ^[2]

Step 5. In Python, the call looks like this (using the Zoho Desk API wrapper pattern):

result = api.get_field_permissions(
    moduleName="tickets",
    fieldId="<your_field_id>",
    p={}          # optional query params
)

The method issues the GET request and returns the permissions object for that field. ^[2]

Step 6. Parse the response. The returned object will describe the permission configuration for the specified field within the given module. If you later need to modify those permissions, a PATCH request to the same path — PATCH /api/v1/organizationFields/{moduleName}/{fieldId}/permissions — accepts a data dictionary containing the updated permission values. ^[6]

---

Common pitfalls

• Missing or insufficient OAuth scopes. If your token was issued without Desk.settings.READ (or Desk.settings.ALL), the API will return an authorisation error. Double-check the scopes list in your OAuth configuration and re-authorise if necessary. ^[3]

• Wrong or missing organisation ID. The Zoho Desk client requires a valid orgId header on every request. If the organisation ID is blank, the client will attempt auto-discovery, but this adds latency and can fail if the account has no organisations returned. Always store and supply the org ID explicitly after the first successful discovery. ^[7]

• Incorrect moduleName casing or spelling. Module names are case-sensitive in the Zoho Desk API path. Use the exact module slug (e.g., tickets, not Tickets) to avoid a 404 or "module not found" error. ^[2]

• Read-only vs. write permissions at the integration level. If your integration is configured with a LOW risk level, only read permissions are available; write and destructive operations require MEDIUM risk or higher. Attempting a PATCH on field permissions without the correct risk level will be blocked before the request is even dispatched. ^[1]

---

What to check

• Scope coverage: Verify that Desk.settings.READ (at minimum) appears in your active OAuth scope string before calling the endpoint. ^[3]
• Path parameters: Confirm both moduleName and fieldId are correct and non-empty; an incorrect field ID will return a 404 or empty permissions object. ^[2]
• Organisation ID: After the API call, ensure the response is not an authentication or "org not found" error — if it is, re-check that the orgId was correctly passed to the Desk client. ^[7]