How to list users under a label in Zoho Desk

Listing users under a label in Zoho Desk is straightforward via the Help Center API — a single GET request returns all users associated with a given label.

Why this matters

Labels in Zoho Desk's Help Center let you segment portal users into meaningful groups, such as premium customers or beta testers. Knowing which users belong to a label is essential for auditing memberships, triggering downstream workflows, or validating that a bulk assignment completed correctly. This operation is also a natural companion to assigning or removing label memberships programmatically.

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

---

Step-by-step

Step 1. Gather your required identifiers.

Before making any API call you need two path parameters: helpcenterid (the ID of the Help Center portal you are working with) and labelid (the ID of the label whose members you want to retrieve). Both are available from your Zoho Desk portal settings or from prior API responses. ^[1]

Step 2. Confirm your OAuth scopes are in place.

Your connected OAuth token must include at minimum Desk.basic.READ to read Help Center data. A broader set of Desk scopes — including Desk.contacts.READ and Desk.settings.READ — is recommended if your integration also manages tickets or contacts alongside label operations. ^[4]

Step 3. Send the GET request.

Issue an HTTP GET to the following endpoint, substituting your real IDs:

GET /api/v1/helpcenter/{helpcenter_id}/labels/{label_id}/users

The optional query parameter p can be passed as a dictionary to support pagination or filtering. ^[1]

Step 4. Use the Python helper method (if applicable).

If your integration uses the Zoho Desk Python client, call the wrapper method directly:

result = desk_api.list_users_under_a_label(
    helpcenter_id="your_helpcenter_id",
    label_id="your_label_id",
    p={}   # optional pagination params
)

This method issues the same GET request internally and returns the parsed response. ^[1]

Step 5. Handle token refresh if needed.

If your access token has expired, the client should automatically invoke a token refresh using the stored refreshtoken. Ensure your integration stores and updates accesstoken and tokenexpiresat after each refresh cycle so subsequent calls succeed without re-authentication. ^[8]

---

Related operations

Once you can list users under a label, you will likely also need:

• Assign a label to multiple users — POST /api/v1/helpcenter/{helpcenterid}/labels/{labelid}/users with a data payload containing the user IDs to add. ^[3]
• Remove users from a label — DELETE /api/v1/helpcenter/{helpcenterid}/labels/{labelid}/users with the appropriate user identifiers. ^[2]
• List all labels belonging to a single user — GET /api/v1/helpcenter/{helpcenterid}/users/{userid}/labels if you need the inverse view (all labels for one user rather than all users for one label). ^[6]

---

Common pitfalls

• Wrong IDs in the path. Mixing up helpcenter_id with an organisation ID or portal slug is the most frequent mistake. Double-check both values before calling the endpoint. ^[1]
• Missing or insufficient OAuth scopes. If the token was generated without the correct Desk scopes, the API will return an authorisation error. Regenerate the token with at least Desk.basic.READ included. ^[4]
• Expired access token not refreshed. If your integration does not implement a token_refresher callback, calls will fail silently after the token expires. Ensure the refresh logic updates the stored token on every renewal. ^[8]

---

What to check

• Verify that the response body contains a list of user objects, confirming the helpcenterid and labelid combination is valid and the label has members. ^[1]
• Confirm your OAuth token includes Desk.basic.READ (and any other required Desk scopes) by inspecting the scopes granted during the OAuth flow. ^[4]
• If you expect a large number of users, check whether the p pagination parameter needs to be incremented to retrieve subsequent pages of results. ^[1]