How to list all tags in Zoho Desk

Listing all tags in Zoho Desk is achievable via the Zoho Desk API using the appropriate OAuth scope and a straightforward API call to retrieve tag data for your organisation.

Why this matters

Tags in Zoho Desk help agents categorise and filter tickets quickly. If you are building an integration, running a data audit, or automating ticket workflows, you will need a programmatic way to enumerate every tag available in your portal. Knowing the correct scope and endpoint saves time and avoids authentication errors.

Step-by-step

Step 1. Ensure your OAuth token includes the right scopes before making any Zoho Desk API call. At a minimum you need Desk.tickets.READ or Desk.basic.READ to interact with Desk resources. For broader settings access — which tag management falls under — include Desk.settings.READ in your scope string. ^[1]

Step 2. Obtain a valid access token for Zoho Desk. If you are using a refresh-token flow, exchange your stored refresh token for a new access token by calling Zoho's OAuth token endpoint. Store the resulting access_token and its expiry so your integration can refresh automatically when the token lapses. ^[7]

Step 3. Identify your Zoho Desk organisation ID (orgId). Every Desk API call requires this value in the request header (orgId: <yourorgid>). If you have not stored it yet, call the organisations endpoint (GET /api/v1/organizations) with your access token. Parse the response — if it returns a data array, take the id field from the first element. Persist this value so you do not need to look it up on every request. ^{[3] [7]}

Step 4. Determine your data-centre domain. Zoho Desk is hosted across multiple regions. Your base URL follows the pattern https://desk.zoho.{dc} where {dc} is your region code (e.g., com, eu, in, com.au). For most accounts the base URL is https://desk.zoho.com. ^[4]

Step 5. Call the Zoho Desk tags endpoint. Construct a GET request to:

GET https://desk.zoho.{dc}/api/v1/tags

Include the following headers:

Authorization: Zoho-oauthtoken <access_token>
orgId: <your_org_id>

You can also pass optional query parameters such as limit and from to paginate through large tag lists. The response will contain a collection of tag objects with their IDs, names, and associated metadata.

Step 6. Parse and display the results. The API returns a JSON body. Iterate over the returned array and extract the fields relevant to your use case — typically id, name, and any department or ticket-count fields included in the payload. ^[6]

Step 7. If you are using an AI-assisted tool like Zpilot (Beam Help's independent Zoho assistant — not official Zoho support), the Desk assistant is pre-configured to call the correct tool automatically. Simply ask it to list tags and it will retrieve live data without guessing. ^[6]

Common pitfalls

• Missing orgId header. Zoho Desk will return a 422 or authentication error if the orgId header is absent. Always auto-discover and persist the org ID on first connection rather than hardcoding it. ^{[3] [7]}
• Insufficient OAuth scopes. Requesting tags under settings may require Desk.settings.READ in addition to ticket-level scopes. If you receive a 401 Unauthorized or scope error, review your full scope string and re-authorise. ^[1]
• Wrong data centre. Using desk.zoho.com when your account is on desk.zoho.eu will result in failed requests. Confirm your region in the Zoho Desk admin panel and update your base URL accordingly. ^[4]
• Expired access tokens. Desk access tokens have a limited lifespan. Implement a token-refresh routine that detects expiry and exchanges the refresh token for a new access token before retrying the call. ^[7]

What to check

• Scopes are correct: Confirm your OAuth token was issued with at least Desk.settings.READ and Desk.basic.READ included in the scope string. ^[1]
• orgId is present and valid: Verify the organisation ID in your request header matches the ID returned by GET /api/v1/organizations for your account. ^{[3] [7]}
• Base URL matches your data centre: Cross-reference the domain in your API calls (desk.zoho.com, desk.zoho.eu, etc.) against the region shown in your Zoho Desk portal settings. ^[4]