> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Zoho CRM

> Connect Zoho CRM to Serval so workflows can manage CRM users, roles, profiles, groups, and territories, and read or write CRM records.

## About Zoho CRM

Zoho CRM is a customer relationship management platform. Serval connects to it through a Serval-managed Zoho OAuth application, so there is nothing to register in the Zoho API Console. You choose which permissions to grant when you connect, and your Zoho data center is detected automatically.

**Authentication:** Zoho OAuth 2.0 with a Serval-managed application. You approve access on Zoho's consent screen; there are no API keys to paste.

**Data sync:** On demand only. Workflows call Zoho CRM at run time through a single API request action. There is no background sync.

## What the Zoho CRM integration enables

| Capability | Description |
| - | - |
| API request action | A single typed action, **Zoho CRM API request**, covering 74 operations from the Zoho CRM v8 API, with automatic authentication and token refresh. |
| User management | List users, invite new users, change a user's role or profile, deactivate users, and delete users. |
| Access structure | Read and manage roles, profiles, user groups, and territories, including which users belong to each. |
| Organization details | Read organization details such as the organization ID, currency, and license counts. |
| CRM records | Read, create, update, upsert, clone, and delete records in any module (leads, contacts, accounts, deals, and custom modules), and read or change module and field metadata. |

Anything in the typed operations can be called from a workflow. For endpoints outside them, see the [Zoho CRM v8 API reference](https://www.zoho.com/crm/developer/docs/api/v8/).

## Before you connect

<Steps>
  <Step title="Pick the Zoho account">
    Sign in with the Zoho account whose CRM organization you want to connect. To use the user, role, profile, group, or territory management permissions, the account must have the Administrator profile in Zoho CRM.
  </Step>

  <Step title="Decide which permissions workflows need">
    Read access to users and organization details is always included. Everything else is optional; see the permission presets below.
  </Step>
</Steps>

<Note>
  Zoho CRM sandbox and developer editions aren't supported. Zoho issues separate tokens for each environment, and Serval connects to production organizations only.
</Note>

## Connect in Serval

<Steps>
  <Step title="Open the connect modal">
    In Serval, go to **Integrations > All integrations > Zoho CRM**. A permissions modal opens.
  </Step>

  <Step title="Select permission presets (all optional)">
    Check any presets your workflows need. Expand a preset to see the exact Zoho scopes it requests.

    | Preset | Zoho scopes requested |
    | - | - |
    | View roles, profiles, groups, and territories | `ZohoCRM.settings.roles.READ`, `ZohoCRM.settings.profiles.READ`, `ZohoCRM.settings.user_groups.READ`, `ZohoCRM.settings.territories.READ` |
    | Manage users | `ZohoCRM.users.CREATE`, `ZohoCRM.users.UPDATE`, `ZohoCRM.users.DELETE`, plus read access to roles and profiles |
    | Manage user groups and territories | `READ`, `CREATE`, `UPDATE`, and `DELETE` on `ZohoCRM.settings.user_groups` and `ZohoCRM.settings.territories` |
    | Manage roles and profiles | `READ`, `CREATE`, `UPDATE`, and `DELETE` on `ZohoCRM.settings.roles` and `ZohoCRM.settings.profiles` |
    | Read CRM records | `ZohoCRM.modules.READ`, `ZohoCRM.settings.modules.READ`, `ZohoCRM.settings.fields.READ` |
    | Create and update CRM records | `ZohoCRM.modules.CREATE`, `ZohoCRM.modules.UPDATE`, plus the read scopes above |
    | Manage modules and fields | `CREATE` and `UPDATE` on `ZohoCRM.settings.modules`, `CREATE`, `UPDATE`, and `DELETE` on `ZohoCRM.settings.fields`, plus read access to both |
    | Delete CRM records | `ZohoCRM.modules.DELETE`, plus `ZohoCRM.modules.READ` |

    Serval never requests Zoho's wildcard `.ALL` scopes.
  </Step>

  <Step title="Click Connect to Zoho CRM">
    Authorization opens in a popup window or a full-page redirect.
  </Step>

  <Step title="Approve on the Zoho consent screen">
    Sign in and approve the requested permissions. Zoho shows the consent screen on every connect and reconnect; this is expected.
  </Step>
</Steps>

<Note>
  `ZohoCRM.users.READ` and `ZohoCRM.org.READ` are always requested, so a connection with no presets selected can still list users and read organization details.
</Note>

Serval detects your Zoho data center (US, EU, IN, AU, JP, CN, CA, SA, or UK) from the authorization response. All API calls and token refreshes then use that data center's servers.

## Changing permissions

Permissions are fixed when you connect. To add or remove permissions, reconnect the integration. The modal opens with the presets you already granted checked. Any granted permission that no checked preset covers is listed under **Keep current permissions** and kept by default; clear that box to drop them. Change the selection and approve on Zoho again.

## Verifying the connection

After connecting, Serval runs three health checks. All three use only the always-included scopes, so they pass regardless of which presets you chose.

**Test Zoho CRM Connection** reads your organization details.

* Success: "Successfully authenticated with Zoho CRM"
* Failure (invalid token or missing scope): "Unable to authenticate with Zoho CRM. The OAuth token is invalid, expired, or missing a required scope. Reconnect the integration."
* Failure (other): "Unable to reach Zoho CRM. Check that the connected Zoho account has access to a CRM organization."

**List Zoho CRM Users** lists a sample of active users.

* Success: "Successfully listed active Zoho CRM users (sample size: \[number])"
* Failure: "Unable to list Zoho CRM users. Reconnect the integration so the ZohoCRM.users.READ scope is granted."

**Read Connected Zoho CRM Account** reads the Zoho user the connection authenticates as.

* Success: "Connected as a Zoho CRM user with the \[profile] profile"
* Failure: "Unable to read the connected Zoho CRM user. Reconnect the integration."

<Tip>
  The user, group, territory, role, and profile management presets only work when the connected account has the Administrator profile. If the third check reports a different profile, reconnect with an administrator account.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Workflows fail with OAUTH_SCOPE_MISMATCH">
    The connection wasn't granted the scope that operation needs. Reconnect and check the preset that covers it. For example, changing a user's role needs **Manage users**.
  </Accordion>

  <Accordion title="Creating or updating records sends emails or changes other records">
    Zoho runs the organization's workflow rules, approvals, and blueprints when records are created or updated through the API. To skip them, pass an empty `trigger` array in the request body (`"trigger": []`).
  </Accordion>

  <Accordion title="User management calls fail even though the scope was granted">
    Zoho only allows administrators to add, change, or delete users. Reconnect while signed in to a Zoho account with the Administrator profile.
  </Accordion>

  <Accordion title="Token refresh stopped working">
    Token refresh is automatic. A persistent authentication failure usually means the grant was revoked in Zoho. Reconnect the integration to create a new grant.
  </Accordion>
</AccordionGroup>