Retrieving the light agent profile in Zoho Desk requires a single authenticated GET request to a dedicated profiles endpoint, returning the profile configuration associated with light agents in your organisation.
Why this matters
Light agents in Zoho Desk have a restricted permission profile compared to full agents — they can view tickets but have limited action rights. Fetching this profile programmatically lets you audit permissions, compare profiles, or build automation that conditionally routes work based on agent type. If you are integrating Zoho Desk into a custom dashboard or internal tooling, knowing the exact profile structure is essential before assigning or filtering agents.
Step-by-step
Step 1. Ensure your Zoho Desk OAuth connection is initialised with the correct organisation ID. The client requires an orgid to route requests to the right Desk portal. If the deskorg_id is not yet stored, the system can auto-discover it by calling the organisations endpoint first and persisting the first returned id value against the user record. [2][5]
Step 2. Confirm that your OAuth token includes the Desk.basic.READ scope (at minimum). Profile and agent data falls under the basic read permission group, so tokens lacking this scope will be rejected before the request reaches the profiles resource. [8]
Step 3. Make sure your access token is valid and not expired. The token refresh mechanism checks the stored refreshtoken, calls the Zoho OAuth token endpoint, and writes the new accesstoken and tokenexpiresat back to the connection record before the API call proceeds. [2][7]
Step 4. Issue the following HTTP request using your authenticated Zoho Desk client:
GET /api/v1/profiles/lightPass any optional query parameters as a dictionary via the p argument (for example, pagination or field filters if supported). The endpoint is identified by the operation name getlightagent_profile. [1]
In Python, using the ZohoDeskApi wrapper, the call looks like this:
result = api.get_light_agent_profile(p={})The p={} argument passes an empty parameter dictionary; replace it with any query parameters your use case requires. [1]
Step 5. Parse the response. The returned object will contain the light agent profile definition. Display or process the key fields — such as profile name, permissions, and ID — according to your integration's needs. If you are building a conversational assistant on top of this, present the data in a human-readable format rather than raw JSON. [3]
Step 6. If you also need to see which agents are currently assigned to the light agent profile, use the companion endpoint:
GET /api/v1/profiles/{profile_id}/agentsSubstitute {profileid} with the id value returned from the previous call. This is handled by the listagentsbyprofile operation and accepts the same optional p parameter dictionary. [4]
---
Common pitfalls
- Missing
orgid: Requests will fail or return unexpected results if the Desk client is initialised without a valid organisation ID. Always verify thatdeskorg_idis populated before making profile calls; the auto-discovery flow handles this on first connection, but a stale or empty value in the database will break subsequent requests. [2][5] - Insufficient OAuth scopes: If
Desk.basic.READis absent from the granted scopes, the profiles endpoint will return an authorisation error. Review the full scope list in your configuration and re-authorise if necessary. [8] - Expired tokens not refreshing: If the
tokenrefresherfunction cannot locate a validrefreshtokenin the database, it returnsNoneand the API call will fail with an authentication error rather than a profile response. Ensure the connection record is intact. [2][7]
---
What to check
- Confirm the response contains a non-empty profile
idfield — you will need this value to calllistagentsby_profilein the follow-up step. [1][4] - Verify that the
Desk.basic.READscope appears in the active token's granted permissions before going to production. [8] - Check that
deskorgidis correctly stored in the connection record so that all subsequent Desk API calls are routed to the right portal. [2][5]
---
*Beam Help provides independent expert support for Zoho products and is not official Zoho support. Always refer to Zoho's own documentation for the latest API changes.*