How to list user badges in Zoho Desk Help Center

Retrieving a complete list of badges awarded to a specific Zoho Desk Help Center user is straightforward via a single GET request to the badges endpoint — here's exactly how our team at Beam Help recommends doing it.

Why this matters

Help Center gamification relies on badges to recognise and reward community contributors. If you are building a custom portal, auditing user engagement, or integrating Zoho Desk data into a third-party dashboard, you will need to programmatically fetch the badges associated with any given user. This is also useful when troubleshooting badge-assignment workflows or verifying that a badge was correctly awarded after calling the add-badges operation.

Step-by-step

Step 1. Gather your required identifiers.

Before making any API call you need two pieces of information: the helpcenterid of the Help Center you are working with, and the userid of the community member whose badges you want to retrieve. Both values are strings and must be substituted into the URL path. If your Desk organisation ID (deskorgid) has not yet been stored in your integration, the system can auto-discover it by calling the organisations endpoint first and persisting the first result. ^[7]

Step 2. Authenticate and initialise the Zoho Desk client.

Your integration must hold a valid OAuth access token for Zoho Desk. If the token has expired, use your stored refreshtoken to obtain a fresh accesstoken before proceeding — the client handles this transparently through a token-refresher callback. Pass the apidomain, accesstoken, and org_id when constructing the ZohoDeskClient. ^[7]

Step 3. Call the List User Badges endpoint.

Issue an HTTP GET request to:

GET /api/v1/helpcenter/{helpcenter_id}/users/{user_id}/badges

Replace {helpcenterid} and {userid} with the actual string values from Step 1. An optional query-parameter dictionary (p) can be passed to support pagination or filtering. ^[1]

Using the Python wrapper, the call looks like this:

response = api.list_user_badges(
    helpcenter_id="your_helpcenter_id",
    user_id="your_user_id",
    p={}          # optional: add pagination params here
)

The method sends a GET request to the constructed path and returns the API response containing the user's badge data. ^[1]

Step 4. Parse and display the response.

Once you receive the response, extract the relevant badge fields — such as badge name, description, and award date — and present them in whatever format your application requires. Our team recommends logging the raw response during development so you can confirm the exact field names returned by your Desk instance. ^[1]

Step 5. (Optional) Combine with related endpoints for richer context.

The same base path supports two additional operations you may find useful alongside listing:

• To award new badges to the user, send a POST to the same /api/v1/helpcenter/{helpcenterid}/users/{userid}/badges path with a data payload describing the badges to add. ^[2]
• To revoke badges, send a DELETE to the identical path. ^[3]
• If you also need the user's community labels, a separate endpoint exists at /api/v1/helpcenter/{helpcenterid}/users/{userid}/labels. ^[6]

Common pitfalls

• Missing or incorrect helpcenter_id: The Help Center ID is not the same as your Zoho Desk organisation ID. Confusing the two will result in a 404 or empty response. Double-check the value in your Desk portal settings.
• Stale access token: Zoho OAuth tokens expire. If your client does not implement automatic token refresh, calls will fail with a 401. Ensure the token-refresher callback is wired up correctly before going to production. ^[7]
• Unpersisted orgid: If deskorg_id is blank in your connection record, the client cannot route requests correctly. The auto-discovery flow resolves this on first use, but only if the authenticated user has permission to call the organisations endpoint. ^[7]
• Pagination not handled: The p parameter supports pagination. If a user has many badges and you omit pagination handling, you may only receive the first page of results. ^[1]

What to check

• Confirm that the helpcenterid and userid values in your request path exactly match the IDs stored in Zoho Desk — a mismatch is the most common cause of empty or error responses. ^[1]
• Verify that your OAuth token is valid and that the associated Zoho Desk profile has Help Center API permissions enabled. ^[7]
• If you expect badges to be present but the list is empty, cross-reference by calling the add-badges endpoint (POST) to ensure badges were successfully assigned before querying. ^[2]

---

*Beam Help provides independent expert guidance for Zoho products and is not official Zoho support. Always refer to your Zoho Desk subscription terms for API rate limits and access entitlements.*