Connecting Zoho CRM — region-aware OAuth sync
The Zoho CRM connector mirrors your Zoho Accounts, Contacts, and Deals into Turtini's CRM. Zoho operates separate data centers per region (US, EU, IN, AU, JP, CN), so the OAuth flow must hit the exact `accounts.zoho.{region}` endpoint that matches your tenant — picking the wrong region results in a "Token-Refresh-Failure" on the first call.
Step 1 — Find your Zoho region:
Sign in to Zoho CRM and look at the URL in your browser. The TLD tells you the data center:
• `.com` → United States
• `.eu` → Europe
• `.in` → India
• `.com.au` → Australia
• `.jp` → Japan
• `.com.cn` → China
Step 2 — Register a self-client in Zoho API Console:
1. Go to `api-console.zoho.{your-region-tld}`
2. Add Client → Self Client (server-to-server) or Server-based Applications
3. For Server-based: set Authorized Redirect URI to `https://{your-turtini-domain}/oauth-callback.html`
4. Copy the Client ID and Client Secret
5. Scopes Turtini will request: `ZohoCRM.modules.accounts.READ`, `ZohoCRM.modules.contacts.READ`, `ZohoCRM.modules.deals.READ`, `ZohoCRM.users.READ`
Step 3 — Connect in Turtini:
1. Settings → Integrations → Zoho CRM card
2. Paste Client ID and Client Secret
3. Pick the region that matches your Zoho tenant
4. Save — credentials go to your org's Secret Manager entry
5. Click "Connect" — a Zoho sign-in popup opens at the correct `accounts.zoho.{region}` endpoint
6. Sign in and approve the requested scopes
7. The popup closes and the connection activates — you'll see the region + API domain (`www.zohoapis.{region}`) + last-sync timestamp
What mirrors over:
• Zoho Accounts → `accounts` (name, website, industry, billing/shipping address, phone)
• Zoho Contacts → `contacts` (name, email, phone, title, linked to parent account)
• Zoho Deals → `opportunities` (name, amount, closing date, stage, account/contact links)
Standard fields only — custom modules and custom fields aren't synced in Phase 1.
Sync cadence + scope toggles work the same as the other CRM connectors: daily scheduled, on-demand "Sync now," and per-object-type checkboxes (Accounts / Contacts / Deals).
Region mismatch is the #1 cause of failed connects:
If you see `invalid_client` or `Token-Refresh-Failure` immediately after Connect, double-check the region picker matches your Zoho URL. The OAuth flow hits a different endpoint per region; using `accounts.zoho.com` for an EU tenant will fail every time. Disconnect, change the region in the credentials form, save, and reconnect.
Refresh tokens:
Zoho refresh tokens don't expire by default (unless your Zoho admin sets a TTL policy). If you do see a refresh failure, click "Reconnect" on the card to run the OAuth popup again with the same credentials — your tokens regenerate without re-entering Client ID/Secret.
Disconnect: clears the stored refresh token; mirrored records stay in Turtini with their Zoho IDs intact so you can reconnect without losing the link.