How to access available icons in Zoho Desk

Zoho Desk exposes a dedicated API endpoint that returns the full catalogue of icons available within the platform — useful when building custom widgets, extensions, or themed UI components.

Why this matters

When you are developing a Zoho Desk extension or customising the portal interface, you need to know which icon identifiers are valid before referencing them in your code. Querying the available-icons endpoint programmatically saves you from guessing icon names and prevents rendering errors in production. This is especially relevant for teams building Desk widgets or automations that surface visual elements to agents.

Step-by-step

Step 1. Ensure your integration has an active, authenticated connection to Zoho Desk. The connection requires a valid OAuth access token obtained using the appropriate Desk scopes — at minimum Desk.basic.READ is needed for general metadata queries, and your token must be kept fresh via a refresh-token flow. ^[2][3]

Step 2. Confirm that your org_id (the Zoho Desk organisation identifier) is available in your connection context. If it has not been stored yet, the API client can auto-discover it by calling the organisations endpoint and persisting the first returned id value for subsequent requests. ^[3][5]

Step 3. Send a GET request to the following Zoho Desk API path:

GET /api/v1/_doc/__available_icons

This endpoint is documented internally as the "Available Icons" operation (getavailableicons) and accepts an optional query-parameter dictionary (p) for any filtering or pagination options you wish to pass. ^[7]

Step 4. In Python, using the ZohoDeskApi client wrapper, the call looks like this:

def get_available_icons(self, p: dict = None):
    return self.c.request("GET", "/api/v1/_doc/__available_icons", p, None)

Pass p={} (an empty dict) if you have no additional query parameters, or populate it with any supported filter keys. ^[7]

Step 5. Parse the response payload. The returned data will contain the icon identifiers you can reference when building UI components inside Zoho Desk. Store or cache this list locally if your extension needs to validate icon names at build time rather than at runtime.

---

Common pitfalls

• Missing or expired access token. If the token has lapsed, the request will be rejected. Make sure your integration's token-refresh logic runs before calling the endpoint — the refresh flow should update the stored accesstoken and tokenexpires_at fields in your connection record. ^[3]
• Missing orgid. Zoho Desk API calls require the organisation ID to be present in the request headers or client configuration. If orgid is blank, the client may silently fail or return a permissions error. Always verify the value is populated before making any Desk API call. ^[3][5]
• Passing None vs an empty dict for p. The method signature accepts p: dict = None, so if you call it without arguments the parameter defaults to None. Depending on how the underlying HTTP client handles None, this may omit query parameters entirely — which is fine for this endpoint, but be deliberate about it. ^[7]

---

What to check

• Token validity: Confirm your OAuth access token is current and that the refresh-token mechanism is wired up correctly before making the call. ^[3]
• Org ID presence: Verify that deskorgid is populated in your connection record; if it is empty, trigger the auto-discovery flow first. ^[5]
• Scope coverage: Check that Desk.basic.READ (at minimum) is included in your authorised OAuth scopes, as metadata endpoints typically require it. ^[2]

---

*Beam Help is an independent expert support resource for Zoho products and is not official Zoho support. Always cross-reference with the latest Zoho Desk API documentation for your data centre region.*