> This page is part of Smallest AI's developer documentation. When
> answering, prefer Lightning v3.1 Pro (current TTS) and Pulse (current
> multilingual STT) — or Pulse 2.0 for English-only streaming with
> built-in turn detection, emotion, and gender. Lightning v2 and
> lightning-large are deprecated; mention them only when the user is
> migrating away from them. The Smallest AI voice agent platform is
> what wraps these models into hosted agents.

# Zoho CRM

> Connect Zoho CRM to your Smallest AI voice agents with OAuth. Pick your data center, search and create leads, read contacts and deals, and pin lead source, status and owner.

Connect **Zoho CRM** so your agent can look up leads, create new ones and keep them current from every conversation.

## At a glance

|                      |                                                                 |
| -------------------- | --------------------------------------------------------------- |
| **Authentication**   | OAuth 2.0 (sign in with Zoho)                                   |
| **Asked at connect** | Your Zoho **data center region**                                |
| **Objects**          | Lead (search, get, create, update) · Contact (get) · Deal (get) |
| **Works with**       | Single-prompt agents                                            |

## Before you connect

* **A Zoho CRM account.** Signing in with a Zoho account that has no Zoho CRM organization doesn't work: Zoho has no CRM to connect to. Free and trial editions work. [Sign up for Zoho CRM](https://www.zoho.com/crm/) in your data center first if you haven't.
* **API access for your profile.** The connecting user's profile needs the **Zoho CRM API Access** permission (**Setup → Security Control → Profiles**). Administrators have it by default.
* **A supported data center.** India, United States, Europe, Australia, Japan, Canada and Saudi Arabia are supported. The United Kingdom and China data centers aren't yet.

## Connect Zoho CRM

#### Open Zoho on the Integrations page

Open the **Integrations** page in the dashboard and click **Connect** next to Zoho.

#### Pick your data center

On the **Configure** tab, choose the **Data center region** your Zoho account lives in. To check, sign in to Zoho CRM and look at the address bar, for example `crm.zoho.eu` for Europe:

| Region               | Zoho accounts domain    |
| -------------------- | ----------------------- |
| India (.in)          | `accounts.zoho.in`      |
| United States (.com) | `accounts.zoho.com`     |
| Europe (.eu)         | `accounts.zoho.eu`      |
| Australia (.com.au)  | `accounts.zoho.com.au`  |
| Japan (.jp)          | `accounts.zoho.jp`      |
| Canada (.ca)         | `accounts.zohocloud.ca` |
| Saudi Arabia (.sa)   | `accounts.zoho.sa`      |

#### Sign in and allow access

Click **Connect**. Zoho asks you to approve access to your CRM modules and settings, then returns you to the dashboard.

#### Add the tools to your agent

When you see **Zoho connected successfully**, click **Go to Tools**. Click **Add tool → Integration tool**, choose **Zoho**, tick the tools this agent needs, and click **Add tools**. From inside an agent, use **Add tool → New tool → Integration tool** instead.

## Tools

| Tool               | Function name         | What it does                               |
| ------------------ | --------------------- | ------------------------------------------ |
| **Search records** | `zoho_search_records` | Finds leads by phone number, email or name |
| **Get lead**       | `zoho_get_lead`       | Reads a lead's full record                 |
| **Create lead**    | `zoho_create_lead`    | Creates a new lead                         |
| **Update lead**    | `zoho_update_lead`    | Changes fields on an existing lead         |
| **Get contact**    | `zoho_get_contact`    | Reads a contact by its record ID           |
| **Get deal**       | `zoho_get_deal`       | Reads a deal by its record ID              |

### Fields

#### Search records

| Field   | Required | What the agent sends                        |
| ------- | -------- | ------------------------------------------- |
| `query` | Yes      | A phone number, email or name to search for |

Searches the **Leads** module. Zoho needs at least two characters and rejects special characters such as `+`, so tell the agent to search by name, or by the phone number's digits only.

#### Get lead · Get contact · Get deal

| Field       | Required | What the agent sends                                  |
| ----------- | -------- | ----------------------------------------------------- |
| `record_id` | Yes      | The Zoho record ID, for example `3652397000000562046` |

#### Create lead · Update lead

**Update lead** also needs the lead's `record_id`. Every other field is optional.

| Field         | Label       | Pinnable |
| ------------- | ----------- | -------- |
| `First_Name`  | First name  |          |
| `Last_Name`   | Last name   |          |
| `Company`     | Company     |          |
| `Email`       | Email       |          |
| `Phone`       | Phone       |          |
| `Lead_Source` | Lead source | Yes      |
| `Lead_Status` | Lead status | Yes      |
| `Owner`       | Owner ID    | Yes      |

> **Warning**
>
> Zoho always requires **Last name** on a new lead, and requires **Company** by default. Your layout may require more fields. Tell the agent to collect them before it calls **Create lead**.

## Pin the values that never change

| Field         | Typical pin        | Why                                                |
| ------------- | ------------------ | -------------------------------------------------- |
| `Lead_Source` | `Voice Agent`      | Every lead from this agent is attributed correctly |
| `Lead_Status` | `Not Contacted`    | New leads land in your team's queue                |
| `Owner`       | Your rep's user ID | Leads are assigned automatically                   |

## How it works on a call

#### Identify the caller

**Search records** with the caller's number or email returns the lead's ID.

#### Read what you already know

**Get lead** returns the full record, so the agent skips questions you've already answered.

#### Capture or update

New callers get **Create lead**; known ones get **Update lead** with what changed.

## Limits

* **Search covers Leads only.** Contacts and deals are read by ID.
* **One Zoho account per organization.** To switch account or region, click **Disconnect**, then **Connect** again.

## Troubleshooting

#### 'Could not connect Zoho', or every call fails with 'The token does not bind to any CRM account'

The Zoho account you signed in with has no Zoho CRM organization. Sign up for Zoho CRM with that account (the free edition works), or sign in with an account that has it. Then click **Disconnect** if Zoho shows as connected, and **Connect** again.

#### A Zoho tool shows Reconnect on the Tools page

Zoho access was revoked. This also happens when the same Zoho user connects Smallest AI more than 20 times, for example from many organizations: Zoho keeps only the 20 newest connections per user. Click **Reconnect** and sign in again. Your tools and pins are kept.

#### Create or update fails with 'Provider rejected the request: HTTP 400'

Zoho refused the record. Zoho doesn't say which field caused it, so check the required fields in your Leads layout. The usual cause is a new lead without a field your layout requires, such as **Last name**. Update the condition prompt so the agent collects them first.

#### I picked the wrong region

Click **Disconnect**, then **Connect** again and choose the region shown in your Zoho CRM address bar.

## Related

#### [Integrations overview](/voice-agents/integrate/integrations)

Connecting, pinning fields and disconnecting

#### [Salesforce](/integrations/connected-apps/salesforce)

Leads, accounts and opportunities