How to get field details in Zoho Desk

Getting field details in Zoho Desk is straightforward once you know the correct API endpoint and have the right OAuth scopes in place. This article walks you through the exact call and what to prepare beforehand.

Why this matters

When building integrations, automations, or custom dashboards on top of Zoho Desk, you often need to inspect the metadata of a specific field — its type, label, allowed values, or whether it is mandatory. Fetching field details programmatically lets you validate data before submission and dynamically render forms without hardcoding field properties. This is especially useful when your organisation has custom fields added to modules like tickets or contacts.

Step-by-step

Step 1. Confirm your OAuth scopes include settings access.

Before making any field-metadata call, verify that your connected OAuth token carries the Desk.settings.READ scope (or the broader Desk.settings.ALL). Without this permission the API will reject the request. Our team at Beam Help — independent expert support for Zoho, not official Zoho support — recommends auditing your scope list during initial setup to avoid silent failures later. ^[4]

Step 2. Identify the two required path parameters.

The endpoint requires exactly two values embedded in the URL path:

• moduleName — the Desk module whose field you want to inspect (for example, tickets, contacts, or accounts).
• fieldId — the unique identifier of the specific field within that module.

You can obtain a fieldId by first calling the list-fields endpoint for the module and noting the id value returned for each field. ^[5]

Step 3. Make the GET request.

Send an authenticated GET request to:

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

Replace {moduleName} and {fieldId} with the values from Step 2. Optionally pass additional query parameters via the p dictionary if your client library supports it. The operation name for this call is getfielddetails. ^[5]

A minimal Python example using the Desk client looks like this:

result = desk_api.get_field_details(
    moduleName="tickets",
    fieldId="<your_field_id>",
    p={}
)

The client issues the HTTP request and returns the field's metadata as a parsed dictionary. ^[5]

Step 4. Ensure your Desk client has a valid organisation ID.

The Zoho Desk API scopes requests to a specific organisation. If your integration has not yet stored a deskorgid, the client will attempt to auto-discover it by calling the organisations endpoint and persisting the first result. Make sure this discovery step has completed successfully before calling field-detail endpoints, otherwise requests may be routed incorrectly. ^{[2] [6]}

Step 5. Handle the response.

The response body contains the field's metadata. Key properties to look for include the field label, data type, maximum length, and whether the field is mandatory or read-only. Display or store only the properties your integration needs, and skip internal IDs that are not meaningful to end users. ^[7]

Common pitfalls

• Missing Desk.settings.READ scope. This is the most frequent cause of 401 or 403 errors when querying organisation fields. Double-check the full scope string in your OAuth configuration — it must explicitly include at least Desk.settings.READ. ^[4]
• Wrong moduleName casing or spelling. Zoho Desk module names in the API path are case-sensitive. Use lowercase values such as tickets, contacts, and accounts rather than their display-name equivalents. ^[5]
• Stale or expired access token. The Desk client relies on a token-refresh callback. If the refresh token itself has expired or been revoked, the auto-refresh will fail silently and subsequent API calls will return authentication errors. Implement logging around the refresh step to catch this early. ^[6]
• Organisation ID not yet discovered. If deskorgid is empty and the auto-discovery call fails (for example, due to a network timeout), field-detail requests will lack the required org context. Always verify the org ID is populated before proceeding. ^[2]

What to check

• Scope coverage: Confirm Desk.settings.READ or Desk.settings.ALL appears in your active OAuth scope list before making the call. ^[4]
• Parameter accuracy: Verify that both moduleName and fieldId are correct by cross-referencing them against the module's full field list first. ^[5]
• Organisation ID persistence: After the first successful API call, check that deskorgid has been stored in your connection record so future requests are routed to the right organisation. ^{[2] [6]}