How to retrieve cases in Zoho

Retrieving cases in Zoho Desk requires a valid OAuth connection, a resolved organisation ID, and the correct API client initialised for the desk app type — all of which our integration handles automatically once your connection is established.

Why this matters

Zoho Desk cases (support tickets) live under a specific organisation context, so any retrieval call must include the correct org_id alongside a live access token. If your token has expired or your organisation ID was never stored, the API call will silently fail or return an authorisation error. Understanding the full flow helps you diagnose issues quickly — and as Beam Help (independent expert support for Zoho, not official Zoho support), we want to make that flow transparent.

Step-by-step

Step 1. Confirm that a Zoho connection record exists for your user account. The system looks up your credentials from the zohoconnections table using your userid. If no record is found, the retrieval process cannot begin and None is returned immediately — you will need to reconnect via OAuth before proceeding. ^[2]

Step 2. Ensure your access token is still valid. The connection layer checks whether the current time is within 120 seconds of the stored tokenexpiresat value. If it is, a proactive refresh is triggered using your refreshtoken before any case data is requested, reducing the chance of a mid-request 401 error. The refreshed accesstoken and updated expiry are written back to the database automatically. ^[2]

Step 3. Initialise the API client with apptype set to "desk". This tells the system to instantiate a ZohoDeskClient rather than the CRM variant. The client is constructed using your stored apidomain, the current accesstoken, your deskorgid, and a tokenrefresher callback that can silently obtain a new token mid-session if needed. ^[1]

Step 4. Allow the system to auto-discover your organisation ID if it is not already stored. When deskorgid is blank, the integration calls getallorganizations and reads the id field from the first item in the returned data list. This discovered value is then persisted so future calls skip the discovery step entirely. ^[1]

Step 5. With the client ready, issue your case retrieval tool call. In the chat or planning stream, the appropriate tool name (for example getrecords targeting the Cases module) is passed to executetoolwithrepair, which runs the query and returns structured results. The system also emits a status message such as "Calling Zoho tool: <toolname>..." so you can confirm the call is in flight. [^3,5]

Step 6. Inspect the returned payload. Successful results come back as a dictionary containing the case records. The system additionally builds contextual links using your dc (data centre), deskorgid, and desk_portal values so you can navigate directly to matching records in the Zoho Desk UI. ^[3]

Step 7. If you are testing the retrieval flow directly (bypassing the chat interface), the direct-call path fetches the most recently created connection record from the database and constructs its own token_refresher closure before invoking the tool. Confirm that at least one connection row exists before running direct tests. ^[4]

Common pitfalls

• Missing orgid: If deskorg_id is an empty string and the auto-discovery call also fails (for example, due to insufficient OAuth scopes), every subsequent Desk API call will be rejected. Verify that your OAuth scopes include access to the Desk organisations endpoint. ^[1]
• Stale refresh token: The refreshtokens method expects a valid refreshtoken in the request body alongside your clientid and clientsecret. If the refresh token has been revoked (e.g., the user re-authorised from a different session), the response will contain an error key rather than access_token, and the connection will be marked unusable. ^[6]
• Wrong apptype: Passing apptype="crm" when you intend to retrieve Desk cases will instantiate the CRM client instead, and case-specific endpoints will not be available. Always confirm the app_type parameter matches the product you are querying. ^[1]
• No connection row in direct tests: The direct-call test harness selects the most recently inserted connection row. If the database is empty or the row was deleted, the call returns {"error": "No Zoho connection found"} immediately. ^[4]

What to check

• Verify that zohoconnections contains a row for your user with a non-empty deskorgid and a tokenexpires_at value in the future. [^1,2]
• Confirm your OAuth scopes were granted with accesstype=offline and prompt=consent so that a refreshtoken is included in the initial token exchange response. ^[6]
• After a successful retrieval, check that the returned payload contains a data list with at least one case object, and that the generated Desk links reference the correct desk_portal subdomain for your account. ^[3]