Zoho CRM Integration

Critical: Tasks Are a Separate Module

Zoho CRM has separate modules for different record types:

Module	Purpose	Key Fields
Leads	Unqualified prospects	Lead_Status, Email, Phone
Contacts	Qualified individuals	Account_Name, Email, Phone
Deals	Sales opportunities	Stage, Amount, Closing_Date
Accounts	Companies/organizations	Account_Name, Industry
Tasks	Action items with due dates	Subject, Due_Date, Status, Priority

Tasks are NOT fields on Leads. They are standalone records that can be associated with Leads, Contacts, Deals, or Accounts via the What_Id field.

Quick Start: Finding Overdue Tasks

When user asks about "overdue" items, they almost always mean Tasks:

code

User: "What are the overdue tasks?" or "What leads are overdue?"

Step 1: ZOHOCRM_SEARCH_RECORDS(module="Tasks", criteria="(Due_Date:less_than:TODAY)")

Done. One call to the Tasks module with a date filter.

Situational Handling

Situation: User asks about "overdue" anything

Trigger phrases: "overdue tasks", "overdue leads", "what's past due", "follow-ups due", "what do I need to do"

Required action: Query the Tasks module, NOT Leads.

code

ZOHOCRM_SEARCH_RECORDS(
  module="Tasks",
  criteria="(Due_Date:less_than:TODAY)"
)

Optional filters:

•By status: (Due_Date:less_than:TODAY)and(Status:equals:Not Started)
•By priority: (Due_Date:less_than:TODAY)and(Priority:equals:Highest)

Situation: User asks about leads/contacts/deals

Trigger phrases: "show me leads", "list contacts", "what deals are closing"

Required action: Query the appropriate module directly.

code

# List leads
ZOHOCRM_SEARCH_RECORDS(module="Leads")

# Leads by status
ZOHOCRM_SEARCH_RECORDS(module="Leads", criteria="(Lead_Status:equals:Contacted)")

# Deals closing this month
ZOHOCRM_SEARCH_RECORDS(module="Deals", criteria="(Closing_Date:between:2026-02-01,2026-02-28)")

Situation: User asks to create a task

Required action: Use the Tasks module with required fields.

code

ZOHOCRM_CREATE_RECORD(
  module="Tasks",
  data={
    "Subject": "Follow up with lead",
    "Due_Date": "2026-02-10",
    "Status": "Not Started",
    "Priority": "High"
  }
)

To associate with a Lead/Contact/Deal, include What_Id:

code

data={
  "Subject": "Follow up",
  "Due_Date": "2026-02-10",
  "What_Id": "7170963000000598816"  # Lead/Contact/Deal ID
}

Situation: User asks about a specific lead's tasks

Required action: Search Tasks filtered by the associated record.

code

Step 1: Find the Lead ID (if not known)
ZOHOCRM_SEARCH_RECORDS(module="Leads", criteria="(Full_Name:contains:John)")

Step 2: Search Tasks associated with that Lead
ZOHOCRM_SEARCH_RECORDS(module="Tasks", criteria="(What_Id:equals:<lead_id>)")

Situation: User asks to update a task

Required action: Get task ID first, then update.

code

Step 1: ZOHOCRM_SEARCH_RECORDS(module="Tasks", criteria="(Subject:contains:follow up)")
Step 2: ZOHOCRM_UPDATE_RECORD(module="Tasks", id=<task_id>, data={"Status": "Completed"})

Module Field Reference

Tasks Module

Field	Type	Values
Subject	String	Task title
Due_Date	Date	YYYY-MM-DD format
Status	Picklist	Not Started, Deferred, In Progress, Completed, Waiting for input
Priority	Picklist	Highest, High, Normal, Low, Lowest
What_Id	Lookup	Associated record ID (Lead, Contact, Deal)
Owner	Lookup	Assigned user

Leads Module

Field	Type	Values
First_Name	String
Last_Name	String
Full_Name	String	Auto-generated
Email	Email
Lead_Status	Picklist	Not Contacted, Contacted, Working, Qualified, etc.
Lead_Source	Picklist	Advertisement, Web, Referral, etc.

Criteria Syntax

Zoho uses COQL-style criteria:

code

(Field_Name:operator:value)
(Field1:equals:value1)and(Field2:contains:value2)
(Field1:equals:value1)or(Field2:equals:value2)

Operator	Usage	Example
equals	Exact match	`(Status:equals:Completed)`
contains	Partial match	`(Subject:contains:follow)`
starts_with	Prefix match	`(Full_Name:starts_with:John)`
less_than	Date/number comparison	`(Due_Date:less_than:2026-02-01)`
greater_than	Date/number comparison	`(Amount:greater_than:10000)`
between	Range	`(Due_Date:between:2026-02-01,2026-02-28)`

Special value: TODAY - use for current date comparisons.

Error Recovery

Error	Cause	Fix
"Module not found"	Wrong module name	Use exact names: Leads, Contacts, Deals, Accounts, Tasks
"Invalid criteria"	Malformed COQL	Check parentheses and operator syntax
"Field not found"	Wrong field name	Use API names (Full_Name, not "Full Name")
"No records found"	Query too restrictive	Broaden criteria, check spelling

Anti-Patterns

Wrong	Right
Search Leads for "overdue" items	Search Tasks module with Due_Date filter
Look for "Next_Action" field on Leads	Tasks are a separate module, not a field
Ask user for field names	Check available fields via ZOHOCRM_GET_FIELDS
Assume Tasks are part of Leads	Tasks are standalone records linked via What_Id
Use date strings like "today"	Use literal dates (2026-02-05) or TODAY keyword

Common Queries

code

# All overdue tasks
ZOHOCRM_SEARCH_RECORDS(module="Tasks", criteria="(Due_Date:less_than:TODAY)")

# Overdue tasks not completed
ZOHOCRM_SEARCH_RECORDS(module="Tasks", criteria="(Due_Date:less_than:TODAY)and(Status:not_equal:Completed)")

# High priority tasks
ZOHOCRM_SEARCH_RECORDS(module="Tasks", criteria="(Priority:equals:High)")

# Tasks due this week
ZOHOCRM_SEARCH_RECORDS(module="Tasks", criteria="(Due_Date:between:2026-02-03,2026-02-09)")

# All leads with status "Contacted"
ZOHOCRM_SEARCH_RECORDS(module="Leads", criteria="(Lead_Status:equals:Contacted)")

# Deals closing this month
ZOHOCRM_SEARCH_RECORDS(module="Deals", criteria="(Closing_Date:between:2026-02-01,2026-02-28)")