How to get agent by email in Zoho Desk

Retrieving an agent's full profile in Zoho Desk by their email address is straightforward using a single REST API call — no need to list all agents and filter manually.

Why this matters

When building integrations, automations, or custom dashboards on top of Zoho Desk, you often know an agent's email address but need their internal agent ID or profile details to perform further operations (such as ticket assignment or reporting). Looking up an agent directly by email saves unnecessary API calls and keeps your code clean.

Step-by-step

Step 1. Ensure you have valid API credentials for Zoho Desk and that your OAuth token includes the necessary scopes to read agent data. Without proper authentication, the request will be rejected before it reaches the agent lookup endpoint.

Step 2. Construct your request using the GET method against the following endpoint, substituting the target address for {agent_email}:

GET /api/v1/agents/email/{agent_email}

For example, to look up jane.doe@yourcompany.com, your request path would be /api/v1/agents/email/jane.doe@yourcompany.com. ^[1]

Step 3. If you are using Python, the call can be wrapped as shown below. Pass the email as the first argument; the optional p parameter accepts a dictionary of any additional query parameters you wish to include:

def get_agent_by_email_id(self, agent_email: str, p: dict = None):
    """Get Agent by Email ID"""
    return self.c.request("GET", f"/api/v1/agents/email/{agent_email}", p, None)

This method issues the GET request and returns the agent object from Zoho Desk. ^[1]

Step 4. Parse the response body. A successful call returns the agent's profile, which typically includes their internal agent ID, display name, role, and department assignments. Store the agent ID if you plan to use it in subsequent API calls such as ticket assignment.

Step 5. Handle non-200 responses gracefully. If the email address does not match any active agent, Zoho Desk will return an error response rather than an empty list. Build error-handling logic around this to distinguish between "agent not found" and network or authentication failures.

Common pitfalls

• URL encoding. Email addresses containing + signs or other special characters must be percent-encoded before being placed in the path segment. Failing to encode the address will result in a malformed request or a 404 response. ^[1]
• Deactivated agents. If the agent account has been deactivated in Zoho Desk, the email may no longer resolve via this endpoint. Verify the agent's status in the Desk admin panel if you receive unexpected errors.
• Case sensitivity. While most systems treat email addresses as case-insensitive, it is best practice to normalise the address to lowercase before passing it to the endpoint to avoid inconsistent results. ^[1]
• Scope permissions. Your OAuth token must have read access to agent resources. If your integration was set up with minimal scopes, the call may return a 403 Forbidden even though the credentials themselves are valid.

What to check

• Confirm the agent email is active in your Zoho Desk portal under Setup → User Management before making the API call, to rule out deactivated-account errors.
• Verify the response contains an agent ID (id field) that you can use in downstream API calls — this is the most common reason teams call this endpoint.
• Test authentication separately by hitting a simpler endpoint (such as listing departments) with the same token, so you can isolate whether any errors are credential-related rather than specific to the agent lookup.

---

*Beam Help is an independent expert support resource for Zoho products and is not official Zoho support. For billing or account-level issues, please contact Zoho directly.*