How to get agent details by IDs in Zoho Desk

Retrieving agent details by one or more agent IDs in Zoho Desk is straightforward using the dedicated bulk-lookup endpoint, which lets you fetch multiple agents in a single API call rather than querying them one at a time.

Why this matters

When building integrations, automations, or reporting dashboards on top of Zoho Desk, you often have a list of agent IDs — perhaps pulled from ticket records — and need to resolve them into full agent profiles. Using the bulk endpoint keeps your API call count low and your code clean. This is especially useful when processing ticket queues or generating agent performance summaries programmatically.

> Note: Beam Help is an independent expert support service and is not official Zoho support.

---

Step-by-step

Step 1. Ensure your Zoho Desk API client is authenticated.

Before making any call, your client must hold a valid access token and the correct orgid for your Desk portal. If the orgid is not yet stored, the client can auto-discover it by calling the organisations endpoint and persisting the first returned organisation ID for all subsequent requests. ^[4][6]

Step 2. Identify the agent IDs you want to look up.

Collect the numeric agent IDs you need to resolve. These are typically found on ticket objects or returned from other Desk API responses. You will pass them as part of the query parameters (p dict) to the endpoint. ^[1]

Step 3. Call GET /api/v1/agentsByIds.

Send a GET request to the /api/v1/agentsByIds endpoint, passing your agent IDs inside the p parameters dictionary. This single call retrieves details for all specified agents at once. ^[1]

Using the Python wrapper the call looks like this:

# p should contain the agent IDs per Zoho Desk's parameter conventions
response = desk_api.get_agent_details_by_agent(p={"ids": "agent_id_1,agent_id_2"})

The method internally issues GET /api/v1/agentsByIds with your supplied parameters. ^[1]

Step 4. (Alternative) Look up a single agent by their unique ID.

If you only need one agent's profile, use the single-agent endpoint instead: GET /api/v1/agents/{agentid}. Substitute {agentid} with the specific agent's ID. ^[7]

response = desk_api.get_agent_details(agent_id="123456789")

This returns the full profile for that one agent. ^[7]

Step 5. (Alternative) Look up an agent by email address.

When you have an agent's email but not their ID, use GET /api/v1/agents/email/{agentemail}, replacing {agentemail} with the address you want to resolve. ^[5]

response = desk_api.get_agent_by_email_id(agent_email="agent@example.com")

This is handy when syncing data from external systems where email is the common identifier. ^[5]

Step 6. (Alternative) List all agents belonging to a specific profile.

If your goal is to enumerate agents grouped by their permission profile, use GET /api/v1/profiles/{profileid}/agents, supplying the relevant profileid in the path. ^[3]

response = desk_api.list_agents_by_profile(profile_id="your_profile_id")

This returns a collection of agents assigned to that profile. ^[3]

---

Common pitfalls

• Missing or stale org_id: Zoho Desk requires the organisation ID to be present in request headers. If it is absent, the client should auto-discover it from the organisations endpoint and persist it — failing to do so will cause all agent lookups to fail. ^[4][6]
• Token expiry: Access tokens expire and must be refreshed using the stored refresh_token. Ensure your client's token-refresh logic is in place before making agent lookup calls; otherwise you will receive authentication errors. ^[4]
• Choosing the right endpoint: Using GET /api/v1/agents/{agent_id} for bulk lookups means one HTTP call per agent. For multiple agents, prefer GET /api/v1/agentsByIds to reduce round-trips. ^[1][7]

---

What to check

• Confirm the org_id is correctly set on your Desk client before making the request — an incorrect or missing org ID is the most common cause of failed agent lookups. ^[4]
• Verify the agent IDs exist in your Desk portal; IDs from a different organisation or a deleted agent will not return valid data. ^[1]
• Check the response structure to ensure the returned payload contains the agent fields your integration expects, and handle empty or partial results gracefully. ^[1][7]