Complex criteria use parentheses and AND/OR: '(Email:equals:
john@example.com
)AND(Last_Name:equals:Doe)'
GET_ZOHO_RECORDS returns all records with optional filtering; SEARCH is for targeted lookups
2. Create Records
When to use
User wants to add new leads, contacts, deals, or other CRM records
Tool sequence
:
ZOHO_GET_MODULE_FIELDS
- Get required fields for the module [Prerequisite]
ZOHO_CREATE_ZOHO_RECORD
- Create a new record [Required]
Key parameters
:
module
Target module name (e.g., 'Leads', 'Contacts')
data
Record data object with field-value pairs
Required fields vary by module (e.g., Last_Name for Contacts)
Pitfalls
:
Each module has mandatory fields; use GET_MODULE_FIELDS to identify them
Field names use underscores (e.g., 'Last_Name', 'Email', 'Phone')
Lookup fields require the related record ID, not the name
Date fields must use 'yyyy-MM-dd' format
Creating duplicates is allowed unless duplicate check rules are configured
3. Update Records
When to use
User wants to modify existing CRM records
Tool sequence
:
ZOHO_SEARCH_ZOHO_RECORDS
- Find the record to update [Prerequisite]
ZOHO_UPDATE_ZOHO_RECORD
- Update the record [Required]
Key parameters
:
module
Module name
record_id
ID of the record to update
data
Object with fields to update (only changed fields needed)
Pitfalls
:
record_id must be the Zoho record ID (numeric string)
Only provide fields that need to change; other fields are preserved
Read-only and system fields cannot be updated
Lookup field updates require the related record ID
4. Convert Leads
When to use
User wants to convert a lead into a contact, account, and/or deal
Tool sequence
:
ZOHO_SEARCH_ZOHO_RECORDS
- Find the lead to convert [Prerequisite]
ZOHO_CONVERT_ZOHO_LEAD
- Convert the lead [Required]
Key parameters
:
lead_id
ID of the lead to convert
deal
Deal details if creating a deal during conversion
account
Account details for the conversion
contact
Contact details for the conversion
Pitfalls
:
Lead conversion is irreversible; the lead record is removed from the Leads module
Conversion can create up to three records: Contact, Account, and Deal
Existing account matching may occur based on company name
Custom field mappings between Lead and Contact/Account/Deal modules affect the outcome
5. Manage Tags and Related Records
When to use
User wants to tag records or manage relationships between records
Tool sequence
:
ZOHO_CREATE_ZOHO_TAG
- Create a new tag [Optional]
ZOHO_UPDATE_RELATED_RECORDS
- Update related/linked records [Optional]
Key parameters
:
module
Module for the tag
tag_name
Name of the tag
record_id
Parent record ID (for related records)
related_module
Module of the related record
data
Related record data to update
Pitfalls
:
Tags are module-specific; a tag created for Leads is not available in Contacts
Related records require both the parent record ID and the related module
Tag names must be unique within a module
Bulk tag operations may hit rate limits
Common Patterns
Module and Field Discovery
1. Call ZOHO_LIST_MODULES to get all available modules
2. Call ZOHO_GET_MODULE_FIELDS with module name
3. Identify required fields, field types, and picklist values
4. Use field API names (not display labels) in data objects
Search Criteria Syntax
Simple search
:
criteria: '(Email:equals:john@example.com)'
Combined criteria
:
criteria: '((Last_Name:equals:Doe)AND(Email:contains:example.com))'
Supported operators
:
equals
,
not_equal
starts_with
,
contains
greater_than
,
less_than
,
greater_equal
,
less_equal
between
(for dates/numbers)
Pagination
Set
per_page
(max 200) and
page
starting at 1
Check response
info.more_records
flag
Increment page until more_records is false
Total count available in response info
Known Pitfalls
Field Names
:
Use API names, not display labels (e.g., 'Last_Name' not 'Last Name')
Custom fields have API names like 'Custom_Field1' or user-defined names
Picklist values must match exactly (case-sensitive)
Rate Limits
:
API call limits depend on your Zoho CRM plan
Free plan: 5000 API calls/day; Enterprise: 25000+/day
Implement delays between bulk operations
Monitor 429 responses and respect rate limit headers
Data Formats
:
Dates: 'yyyy-MM-dd' format
DateTime: 'yyyy-MM-ddTHH:mm:ss+HH:mm' format
Currency: Numeric values without formatting
Phone: String values (no specific format enforced)
Module Access
:
Access depends on user role and profile permissions
Some modules may be hidden or restricted in your CRM setup
Custom modules have custom API names
Quick Reference
Task
Tool Slug
Key Params
List modules
ZOHO_LIST_MODULES
(none)
Get module fields
ZOHO_GET_MODULE_FIELDS
module
Search records
ZOHO_SEARCH_ZOHO_RECORDS
module, criteria
Get records
ZOHO_GET_ZOHO_RECORDS
module, fields, per_page, page
Create record
ZOHO_CREATE_ZOHO_RECORD
module, data
Update record
ZOHO_UPDATE_ZOHO_RECORD
module, record_id, data
Convert lead
ZOHO_CONVERT_ZOHO_LEAD
lead_id, deal, account, contact
Create tag
ZOHO_CREATE_ZOHO_TAG
module, tag_name
Update related records
ZOHO_UPDATE_RELATED_RECORDS
module, record_id, related_module, data
When to Use
This skill is applicable to execute the workflow or actions described in the overview.