How to retrieve timeline in Zoho

Retrieving a timeline in Zoho requires a valid OAuth access token and a properly maintained connection to the Zoho API — once those are in place, your integration can call the relevant tools to pull back timeline data for any supported module.

Why this matters

Timeline data gives you a chronological view of activity against a record — useful for auditing changes, reviewing communication history, or building reports. If your access token has expired or your connection is misconfigured, any attempt to fetch timeline information will fail silently or return a 401 error. Understanding how the authentication layer works is therefore a prerequisite before making any data retrieval call.

> Note: Beam Help is independent expert support for Zoho — we are not official Zoho support.

---

Step-by-step

Step 1. Establish your OAuth connection.

Before anything else, your application must complete the OAuth flow. The authorisation URL is constructed using your clientid, redirecturi, configured scopes, and the parameters responsetype=code, accesstype=offline, and prompt=consent. Once the user approves, Zoho redirects back with an authorisation code. ^[7]

Step 2. Exchange the authorisation code for tokens.

POST the authorisation code to Zoho's token endpoint using granttype=authorizationcode along with your clientid, clientsecret, and redirecturi. A successful response returns an accesstoken, a refreshtoken, an apidomain, and an expires_in value. Store all of these — you will need them for every subsequent request. ^[7]

Step 3. Persist the connection and track expiry.

Save the accesstoken, refreshtoken, tokenexpiresat (calculated as current Unix time plus expiresin), and apidomain to your data store. The expiry timestamp is critical: it tells your system when the token needs to be refreshed before making API calls. ^[1]

Step 4. Refresh the token before it expires.

When retrieving the stored connection, check whether the current time is within 120 seconds of tokenexpiresat. If so, POST to the token endpoint with granttype=refreshtoken, your clientid, clientsecret, and the stored refreshtoken. On success, update the stored accesstoken and tokenexpiresat with the new values. This 120-second buffer reduces the chance of a mid-request token expiry. ^{[2] [3]}

Step 5. Confirm the connection is active before calling any tool.

After the refresh logic runs, verify that a valid connection object exists for the user. If no connection is found — for example, because the user has never authorised or the refresh failed — surface a reconnection prompt rather than proceeding. Attempting to call Zoho tools without a live token will result in an error response. ^[6]

Step 6. Identify the correct tool and module for timeline retrieval.

With a valid connection in hand, determine which Zoho tool maps to timeline data for your target module (for example, Contacts, Leads, or Deals in Zoho CRM). The api_domain returned during token exchange is the base URL for all API calls — use it when constructing your ZohoCrmClient. Pass the tool name and any required parameters (such as module) to the execution layer. ^[4]

Step 7. Execute the tool call.

Invoke the tool via your API execution layer, supplying the tool name and a parameters dictionary. The system will call Zoho's API using the current access token and return the timeline payload. If the token has rotated mid-session, the token refresher callback will automatically obtain a new one and retry. ^{[4] [5]}

Step 8. Handle the response.

A successful call returns the timeline records as structured data. If the response contains an error key, inspect the message — common causes include an expired token that failed to refresh, an invalid module name, or insufficient OAuth scopes. ^{[3] [4]}

---

Common pitfalls

• Missing refreshtoken on subsequent exchanges. Zoho only returns a refreshtoken on the very first authorisation. If you lose it, the user must re-authorise from scratch. Always persist it immediately after the initial code exchange. ^[7]
• Token expiry not tracked correctly. tokenexpiresat must be set as int(time.time()) + int(expires_in) at the moment the token is received — not at the moment it is stored. Any delay between receipt and storage will cause premature expiry calculations. ^{[1] [3]}
• Wrong apidomain used. The apidomain in the token response may differ by data centre (e.g., .com, .eu, .in). Always use the domain returned in the token exchange rather than hardcoding a URL. ^[7]
• Org ID field inconsistency. When fetching user info from https://accounts.zoho.<DC>/oauth/user/info, the organisation ID may appear under orgid, organizationid, or ZGID depending on the data centre. Build fallback logic to handle all variants. ^[1]

---

What to check

• Token is valid and not within 120 seconds of expiry before issuing any timeline retrieval call — confirm the refresh logic ran successfully and the new access_token was persisted. ^[2]
• api_domain matches the user's data centre — verify the domain stored during token exchange is being used as the base URL for all Zoho API requests. ^{[4] [7]}
• Required OAuth scopes are included — ensure the scopes configured in your authorisation URL cover read access to the module whose timeline you are querying. ^[7]