How to retrieve tags and followers in Zoho Desk

Tags and followers for a Zoho Desk document can be retrieved with a single authenticated GET request to the dedicated tags-and-followers endpoint. This article walks you through exactly how to do that using the Zoho Desk API.

Why this matters

When building integrations or automations around Zoho Desk, you often need to know which tags are attached to a document and who is following it — for example, to trigger notifications or filter content by topic. The tags_followers operation gives you both pieces of information in one call. Understanding how authentication and organisation IDs are resolved beforehand is equally important, because a missing orgId will silently break the request. (Note: Beam Help is independent expert support for Zoho — we are not official Zoho support.)

---

Step-by-step

Step 1. Ensure you have an active Zoho Desk connection with a valid access token and a resolved organisation ID (orgId). The orgId is stored against your connection record; if it is absent, the system will call getallorganizations automatically, pick the first organisation returned, and persist that ID for future requests. ^[2]

Step 2. Instantiate a ZohoDeskClient by supplying your API domain, current access token, orgId, and a token-refresh callback. Wrap it in a ZohoDeskApi object so you can call higher-level methods. ^[2]

Step 3. Make sure your access token is still valid. The token-refresh callback queries the stored refreshtoken, calls ZohoOAuth.refreshtokens, and — if an access_token key is present in the response — writes the new token and its expiry back to the database before returning it. This happens transparently before any API call. ^[2]

Step 4. Call the tags-and-followers operation. The method signature is:

def get_tags_followers(self, p: dict = None):
    """Tags & Followers"""
    return self.c.request("GET", f"/api/v1/_doc/tags___followers", p, None)

Pass any query parameters you need as a dictionary in the p argument (for example, pagination or filter keys). If you have no extra parameters, pass an empty dict or None. ^[5]

Step 5. The underlying client issues a GET request to the path /api/v1/doc/tags__followers on your configured API domain, with the orgId injected as a required header or query parameter by the client layer. The response contains the tags and follower data for the targeted document. ^[5]

Step 6. Parse the returned payload. Present the key fields — such as tag names and follower identifiers — directly to the end user or feed them into your downstream logic. The assistant layer is designed to surface these fields in a readable, line-break-separated format rather than raw JSON. ^[7]

---

Common pitfalls

• Missing orgId: If the organisation ID has never been stored, the first API call will attempt auto-discovery. If getallorganizations returns an unexpected structure (neither a dict with a "data" key nor a plain list), orgId will remain blank and subsequent requests will fail. Always verify that deskorgid is populated in your connection record after the first successful call. ^[1][2]

• Expired access token: The refresh callback only succeeds when the stored refreshtoken is still valid and the OAuth response contains an accesstoken key. If the refresh itself fails, the callback returns None and the API call will be rejected. Re-authenticate the connection if you see repeated token errors. ^[2]

• Wrong apptype: The ZohoDeskClient and ZohoDeskApi are only instantiated when apptype is set to "desk". Passing "crm" will route the request to the CRM client instead, which does not expose the gettagsfollowers method. ^[2]

---

What to check

• Confirm that deskorgid is non-empty in your connection record before making the call — a blank value triggers auto-discovery on every request, adding unnecessary latency. ^[1][2]
• Verify the HTTP response status from /api/v1/doc/tags__followers; a 401 indicates a token problem, while a 403 usually points to an incorrect or missing orgId header. ^[5]
• After retrieving the data, check that both the tags array and the followers list are present in the payload — an empty result may mean the document has no tags or followers yet, rather than an error in your request. ^[5]