Connect Zoho CRM

Pipemetry reads your Zoho deals, their change history, your Deals field settings (which is where your stage list lives), and how many contacts are attached to each deal. It never writes to Zoho — the only non-GET call this connector makes is minting its own access token.

The same walkthrough is built into the app, on the Zoho CRM card under Onboarding.

What Pipemetry needs from you

Four values, all of them on one form:

Value	Notes
Data centre	Required, and validated. There is no default — see below
Client ID	From a Self Client in the Zoho API Console
Client secret	The same Self Client
Refresh token	Exchanged from a grant code with the two scopes below

The client secret and the refresh token are write-only: they are encrypted before they are stored and are never returned, so those fields are blank whenever you reopen the form.

The data centre is not a detail

Zoho is multi-region, and a refresh token is bound to one region. Used against another it fails in a way that reads exactly like bad credentials — valid credentials, wrong host. That is why Pipemetry asks for the region explicitly and refuses to guess one, and why it shows the region back to you on the card once you are connected.

Look at the address bar in Zoho CRM: the domain is your region. Pipemetry supports United States (zoho.com), Europe (zoho.eu), India (zoho.in), Australia (zoho.com.au) and Japan (zoho.jp).

Step 1 — Create a Self Client

In the Zoho API Console for your region, add a client of type Self Client, then copy its Client ID and Client Secret.

Step 2 — Generate a grant code with these scopes

ZohoCRM.modules.ALL,ZohoCRM.settings.ALL

Two scopes, one per thing Pipemetry reads:

• ZohoCRM.modules.ALL covers the deals themselves (/crm/v8/Deals), the deal history records (DealHistory), the per-deal __timeline, the deleted-records feed, and a deal’s Contact_Roles.
• ZohoCRM.settings.ALL covers one endpoint: the Deals field settings, which is where your Stage picklist and its forecast categories come from.

Why modules.ALL is broader than what Pipemetry uses

Zoho grants CRM access per module, not per operation, so modules.ALL carries write permission across your modules. Pipemetry only ever reads. A narrower read-only spelling has not been proven against a live Zoho org yet, and a scope string Zoho rejects fails the grant outright rather than degrading — so the guide asks for the grant that is known to work and says plainly that it is wider than the use. You own the Self Client and can revoke it in the API Console at any time.

Step 3 — Exchange the code straight away

The grant code expires in about 10 minutes. Swap it for a refresh token, which is durable — Pipemetry mints short-lived access tokens from it.

Step 4 — Connect in Pipemetry

On the Zoho CRM card: pick your Data centre, paste the Client ID, Client secret and Refresh token, then Connect Zoho.

Then click Test connection. It separates two facts that need different fixes:

• Could we sign in? If not, the credential or the region is wrong.
• Could we read deals? Signing in and then failing to read deals is a permission problem, not a credential one, and the card says which of the two happened.

On success it reports how many deals it could read, how many stages your Deals module defines, and whether your Stage picklist supplied its own forecast categories — when it did, your configuration decides how deals are grouped rather than a Pipemetry-derived rule.

Step 5 — Import your history

Click Import history. This import is synchronous — the counts come back in the response rather than in a “we will email you” job.

Pipemetry sweeps both of Zoho’s history paths and merges them:

• DealHistory is the broad path — one paged sweep covering every deal, but its rows are snapshots: a new value with no old value.
• the per-deal __timeline is the deep path — it covers only deals that have actually been edited, but it carries true old → new pairs with a timestamp.

Where the two describe the same change, the timeline event wins, because the old value is the thing that makes this connector richer than a change stream that supplies none. The bulk path then fills every gap the timeline leaves.

The result tells you how many changes were written across how many deals, and — separately — how many deals have no change history yet. That is normal, not a fault: a deal nobody has edited since it was created has nothing to record. It is the difference between “no history” and “nothing has changed yet”.

Field mapping: not editable yet

There is no field-mapping editor for Zoho, and the card says so rather than leaving you to infer it from a missing section. Pipemetry reads the standard Deal fields:

Pipemetry field	Zoho API name
amount	Amount
stage	Stage
close date	Closing_Date
owner	Owner
created date	Created_Time

You cannot yet point a Pipemetry field at one of your custom fields on this connector.

Won/lost and open/closed are not read from the deal. Zoho states closedness per stage, so Pipemetry takes them from your Stage picklist — which is why the settings scope above is required and not optional.

How the sync stays current

Zoho sync is scheduled, not real-time

Pipemetry polls Zoho on a schedule: each run reads what changed since the last successful pass, sweeps for deleted deals, and only then advances its cursor. The default cadence is hourly. A run that fails does not move the cursor, so the window it missed is covered by the next one rather than skipped for ever.

There is no live change stream for Zoho. Live streaming exists on the Salesforce connector only, and Pipedrive can push over webhooks; Zoho does neither today, so nothing in the app claims real-time for it. The connectors list in Settings labels this connector’s freshness stamp Last polled rather than Live, and offers a Sync now button when you do not want to wait for the next tick.

Deleted deals matter more than they look. Reconstruction is last-write-wins, so a deal that merely stops appearing would keep contributing its amount to every forecast. Pipemetry sweeps Zoho’s deleted-records feed and retracts them — and when it could not run that sweep it records that it could not look, rather than concluding nothing was deleted.

What the single-threaded-deal alert needs

Pipemetry reads each deal’s Contact Roles and keeps only how many there are. That count is what the single-threaded-deal alert is computed from; a deal with no count is skipped, so an org where the count is unreadable produces an empty alert list — which looks exactly like a pipeline with no single-threaded deals in it. The card therefore reports whether the sweep could look at all.

This read needs no extra consent: ZohoCRM.modules.ALL, which the grant above already includes, covers it. So an unanswered sweep points at the connection or the endpoint rather than at a missing permission.

Zoho says “You are not a part of any CRM service orgs”

Your Zoho account exists but Zoho CRM has not been set up on it yet, so there is no organisation for the CRM scopes to apply to. Open crm.zoho.com, complete the first-run setup, then generate the grant code again.

Disconnecting

Disconnect deletes the stored credentials for the workspace, and then ends the deals this connector wrote. That second half matters: the event log is append-only, so without it every deal Zoho ever imported would keep reconstructing as live pipeline — in the pipeline view, in the forecast and in alert emails — for a CRM you removed. An as-of-day read of the past is left exactly as it was, and reconnecting restores the deals.