How to retrieve a specific role in Zoho Desk

Retrieving a specific role in Zoho Desk is straightforward once you know which API endpoint to target and have the correct OAuth scopes in place. This guide walks you through the two role-retrieval operations available and how to call them correctly.

Why this matters

Role data in Zoho Desk controls what agents can see and do inside your helpdesk. You may need to fetch a specific role to audit permissions, synchronise role assignments with an external system, or simply confirm which role is attached to the currently authenticated agent. Knowing the right endpoint saves you from guessing at the API structure and avoids unnecessary trial-and-error.

> Beam Help is independent expert support for Zoho — we are not official Zoho support.

---

Step-by-step

Step 1. Confirm your OAuth scopes include Desk.basic.READ before making any role-related calls. The Zoho Desk OAuth scope list requires at minimum Desk.basic.READ (and optionally Desk.basic.CREATE) to access organisational data such as agents, departments, and roles. ^[2]

Step 2. Decide which role you need. There are two distinct operations depending on your goal:

• Your own (personal) role — use the /api/v1/roles/mine endpoint.
• A specific role by its ID — this is handled differently depending on whether you are working in the Desk or CRM context (see Step 4 below).

Step 3. To fetch the role assigned to the currently authenticated agent, send a GET request to /api/v1/roles/mine. In code, this maps to the getpersonalrole operation, which accepts an optional parameters dictionary p and returns the role details for the logged-in user. ^[4]

GET /api/v1/roles/mine

Pass any optional query parameters as key-value pairs in the p argument. If you have no filters, an empty dict {} is sufficient. ^[4]

Step 4. If you need to look up a role by a known role ID within Zoho CRM (for example, when cross-referencing agent roles between CRM and Desk), use the get_role operation, which targets:

GET /settings/roles/{rid}

Replace {rid} with the alphanumeric role identifier. This call requires only the role ID as a path parameter — no request body is needed. ^[5]

Step 5. Similarly, if you need to retrieve a contact-level role tied to a deal in Zoho CRM, a separate endpoint exists:

GET /Contacts/roles/{role_id}

This getcontactrole operation accepts the role_id as a path parameter and returns the deal contact role record. ^[7]

Step 6. Make sure your Zoho Desk client is initialised with a valid orgid before calling any Desk endpoint. The client requires the API domain, a current access token, and the organisation ID. If the orgid is missing, the system can auto-discover it by first calling the organisations list endpoint and reading the first result's id field, then persisting it for subsequent requests. ^[1]

Step 7. Handle token expiry gracefully. Access tokens can expire between calls. Implement a token-refresh routine that reads the stored refreshtoken, calls the OAuth refresh endpoint, and writes the new accesstoken and tokenexpiresat values back to your data store before retrying the role request. ^[1]

---

Common pitfalls

• Missing Desk.basic.READ scope. Role endpoints sit under the "basic" scope group. If this scope was not included when the OAuth connection was authorised, all role calls will return a permissions error. Re-authorise the connection with the full scope list to resolve this. ^[2]
• Wrong endpoint for context. /api/v1/roles/mine returns *your* role; /settings/roles/{rid} fetches *any* role by ID but lives in the CRM API layer. Mixing these up will produce 404 or unexpected results. [^4,5]
• Missing or empty orgid. Zoho Desk API calls require the organisation ID to be passed in the request headers. If orgid is an empty string, the client will fail silently or return an organisation-not-found error. Always verify the value is populated before making the call. ^[1]
• Stale access token. Desk API calls made with an expired token will return an authentication error. Ensure your token-refresh logic runs before the call, not only after a failure, to avoid unnecessary retries. ^[1]

---

What to check

• Scope coverage: Verify that Desk.basic.READ appears in your active OAuth scope string and that the connection was authorised with it included. ^[2]
• Correct endpoint selection: Confirm you are calling /api/v1/roles/mine for the personal role or /settings/roles/{rid} with a valid role ID for a specific role lookup. [^4,5]
• orgid is populated: After initialising the Desk client, log or inspect the orgid value to ensure it is a non-empty string before any API call proceeds. ^[1]