How to retrieve agent photo in Zoho Desk

Retrieving an agent's profile photo in Zoho Desk is straightforward via the REST API — a single authenticated GET request to the agent photo endpoint returns the image for the specified agent.

Why this matters

When building custom portals, internal dashboards, or integrations that display support team information, you may need to pull each agent's profile picture programmatically rather than relying on the Zoho Desk UI. This is also useful for syncing agent avatars into third-party tools or generating branded reports that include agent headshots alongside ticket data. As independent expert support (not official Zoho support), Beam Help walks you through exactly how to do this.

Step-by-step

Step 1. Ensure you have a valid Zoho Desk API connection in place, including a current OAuth access token and your organisation's orgid. If your token has expired, your integration should call the token refresh flow to obtain a fresh accesstoken before proceeding. ^[7]

Step 2. Identify the agent_id of the agent whose photo you want to retrieve. This is the unique identifier assigned to the agent within your Zoho Desk organisation. You can obtain it from a prior call to the agents list endpoint or from your local database if you have already synced agent records. ^[1]

Step 3. Make an authenticated HTTP GET request to the agent photo endpoint:

GET /api/v1/agents/{agent_id}/photo

Replace {agent_id} with the actual agent identifier. The endpoint also accepts an optional query parameter p if you need to pass additional parameters. ^[1]

Step 4. If you are working in Python, the call can be structured as shown below — this wraps the request cleanly and passes any optional parameters through the p dictionary:

def get_agent_photo(self, agent_id: str, p: dict = None):
    """Get Agent Photo"""
    return self.c.request("GET", f"/api/v1/agents/{agent_id}/photo", p, None)

Pass None (or an empty dict) for p if you have no additional query parameters to include. ^[1]

Step 5. Handle the response in your application. The API will return the photo data for the specified agent. Incorporate appropriate error handling for cases where the agent has no photo set, or where the agent_id is invalid, to avoid unhandled exceptions in your integration. ^[1]

Step 6. If your Zoho Desk client does not yet have an orgid stored, make sure your initialisation logic auto-discovers it by calling the organisations endpoint first, then persisting the returned id for subsequent requests. Without a valid orgid, Zoho Desk API calls will fail. ^[7]

Common pitfalls

• Expired access tokens — Zoho OAuth tokens have a limited lifespan. Always implement a token refresh mechanism that checks expiry before making API calls and updates the stored accesstoken and tokenexpires_at values after a successful refresh. ^[7]
• Missing or incorrect orgid — The Zoho Desk API requires the organisation ID to be present (typically as a request header). If your connection record does not have deskorg_id populated, the request will be rejected. Build in auto-discovery logic that fetches the org list on first use and stores the result. ^[7]
• Invalid agentid — Passing an agentid that does not exist in your Zoho Desk organisation will result in an error response. Always validate or source agent IDs from a reliable agents list call rather than hardcoding them. ^[1]

What to check

• Confirm that your OAuth access token is valid and has not expired before making the photo request. ^[7]
• Verify that the agent_id you are supplying matches an active agent record in your Zoho Desk organisation. ^[1]
• Ensure your API client is initialised with the correct org_id; if it is blank, trigger the auto-discovery flow before calling the photo endpoint. ^[7]