Zoho

Integrate Zoho Analytics with Catalog to sync dashboards, reports, and semantic metadata. You can use Catalog-managed OAuth credentials or prepare uploads yourself using the BI Importer format. Catalog-managed Zoho onboarding is still maturing and involves OAuth codes that expire quickly, so this page walks through credential JSON, regional server hosts, handoff options, and frequent OAuth failures.

Requirements

You must be a Zoho Analytics Account Administrator to create OAuth 2.0 credentials such as Client ID and Client Secret for the APIs Catalog calls.

Catalog Managed

Use this section when Catalog stores your Zoho credentials and runs scheduled sync for your Workspace.

Integration in progress

Catalog-managed Zoho onboarding is still maturing. Plan credential handoff quickly after you generate OAuth codes because Self Client authorization codes expire within minutes. For a self-contained path you fully control today, use Client Managed with BI Importer.

Regional Server URI Examples

Pick the server_uri host from the same region where your Zoho Analytics account lives. Zoho publishes the authoritative list in Zoho Server URI documentation. Common examples:

Region or deployment	Example server_uri host
United States	analyticsapi.zoho.com
Europe	analyticsapi.zoho.eu
India	analyticsapi.zoho.in
Australia	analyticsapi.zoho.com.au
Japan	analyticsapi.zoho.jp
Canada	analyticsapi.zohoanalytics.ca

Always confirm the latest host names in Zoho's documentation before go-live, especially if Zoho adds regions or changes endpoints.

Prepare OAuth Values

Gather the following before you paste JSON into Catalog or Safenote:

• Server URI - Pick the host name from Regional Server URI Examples that corresponds to your account region.
• Client ID and Client Secret from your Self Client registration.
• Authorization code from the Self Client consent flow (Zoho self client documentation).

Self Client settings commonly include:

• Client Type - Self Client
• Scope - ZohoAnalytics.metadata.read
• Time Duration - 3 hours, the maximum Self Client duration Zoho documents for this flow

See Zoho Analytics API Documentation for the latest OAuth steps.

Send Credentials to Catalog

You can send credential bundles through Safenote over Slack or email when your onboarding asks for it. Use JSON shaped like this, replacing placeholders with your real values:

{
    "server_uri": "analyticsapi.zoho.com",
    "client_id": "1234",
    "client_secret": "1234",
    "code": "1234"
}

Use the host name that matches your Zoho data center, not the placeholder analyticsapi.zoho.XXX literal string.

For your first sync, allow up to 48 hours after Catalog confirms credentials. Catalog notifies you when the initial sync completes.

If you prefer not to share credentials with Catalog operations, continue to Client Managed.

Client Managed

Doing a One-Time Extract

For a trial or one-time snapshot, assemble Zoho Analytics metadata into BI Importer expected format, then upload using the channel your Catalog contact provides.

The Catalog extractor package published on PyPI includes dedicated command-line entry points for several BI platforms. There is not yet a published castor-extract-zoho command in that package. Until a Zoho-specific command ships, rely on BI Importer formatting and upload flows. You can use the shared Google Colab notebook to explore extraction patterns for other tools while you build Zoho exports manually or with custom scripts.

Zoho to Catalog Translation

Zoho element mapping

Zoho elements map to Catalog dashboard_type values as follows:

• Zoho Table - VIZ_MODEL
• Zoho Dashboard - DASHBOARD
• Zoho Report - TILE

Common Issues

For redirect URI mismatches, scope errors, and the general flow to update credentials in Catalog after a vendor-side OAuth change, see Integration OAuth troubleshooting. Then use the Zoho-specific checks below when OAuth handoff fails or metadata looks wrong in Catalog:

• Invalid or expired OAuth code - Self Client authorization codes expire within minutes. Generate a fresh code in Zoho, then paste it into Safenote or Catalog immediately. If your team cannot complete handoff the same day, regenerate the code right before you send it.
• Wrong data center - Symptoms include DNS failures or authentication errors against analyticsapi.zoho.*. Match server_uri to the region where your Zoho Analytics account was created using Zoho Server URI documentation.
• Insufficient scope - Confirm the Self Client includes ZohoAnalytics.metadata.read so Catalog can read analytics metadata.

What's Next?

• Browse related setup patterns on BI Tools.
• Review file layout and columns for uploads in BI Importer.

---