Manage Zoho CRM from Your AI Agent with the Zoho-CRM Skill: Full CRUD Operations Without OAuth Hassle

If you've ever tried to integrate Zoho CRM into an automation workflow, you know the OAuth dance can be painful. Access tokens expire, refresh tokens need managing, and suddenly your agent is broken at 3 AM because a token expired. The zoho-crm skill solves this elegantly by routing all API calls through Maton's managed OAuth gateway—you authenticate once and forget about it.

Who Needs This?

• Sales teams who want their AI agent to log calls, update deals, or search contacts hands-free
• Ops/automation builders integrating CRM data into broader workflows
• Developers who want CRM access without building OAuth infrastructure
• Anyone tired of Zoho's OAuth token expiry headaches

Installation

clawdhub install zoho-crm

That's it for the skill. But you'll also need to set up authentication:

1. Get your Maton API key:

• Sign up or log in at maton.ai
• Go to maton.ai/settings
• Copy your API key

2. Set the environment variable:

export MATON_API_KEY="your_api_key_here"

3. Connect your Zoho CRM account:

import urllib.request, os, json

data = json.dumps({"app": "zoho-crm"}).encode()
req = urllib.request.Request("https://ctrl.maton.ai/connections", data=data, method="POST")
req.add_header("Authorization", f"Bearer {os.environ[MATON_API_KEY]}")
req.add_header("Content-Type", "application/json")
result = json.load(urllib.request.urlopen(req))
print(result["connection"]["url"])  # Open this URL to authorize

Open the returned URL in your browser and authorize the OAuth connection. Once done, you're set.

Usage Examples

Example 1: List Your Latest Leads

import urllib.request, os, json

req = urllib.request.Request(
    "https://gateway.maton.ai/zoho-crm/crm/v8/Contacts/search?email=john@example.com"
)
req.add_header("Authorization", f"Bearer {os.environ[MATON_API_KEY]}")
result = json.load(urllib.request.urlopen(req))

for contact in result.get("data", []):
    print(f"Found: {contact[First_Name]} {contact[Last_Name]}")

Example 2: Create a New Lead

import urllib.request, os, json

lead_data = json.dumps({
    "data": [{
        "Last_Name": "Martinez",
        "First_Name": "Sofia",
        "Email": "sofia.martinez@example.com",
        "Company": "TechStartup Inc",
        "Phone": "+1-555-0199"
    }]
}).encode()

req = urllib.request.Request(
    "https://gateway.maton.ai/zoho-crm/crm/v8/Leads",
    data=lead_data,
    method="POST"
)
req.add_header("Authorization", f"Bearer {os.environ[MATON_API_KEY]}")
req.add_header("Content-Type", "application/json")

result = json.load(urllib.request.urlopen(req))
print(f"Created lead with ID: {result[data][0][details][id]}")

Example 3: Search for Contacts by Email

import urllib.request, os, json

req = urllib.request.Request(
    "https://gateway.maton.ai/zoho-crm/crm/v8/Contacts/search?email=john@example.com"
)
req.add_header("Authorization", f"Bearer {os.environ[MATON_API_KEY]}")
result = json.load(urllib.request.urlopen(req))

for contact in result.get("data", []):
    print(f"Found: {contact[First_Name]} {contact[Last_Name]}")

Key Configuration Notes

Base URL: All requests go through https://gateway.maton.ai/zoho-crm/crm/v8/{endpoint}

Required Header: Every request needs Authorization: Bearer $MATON_API_KEY

Module names are case-sensitive: Use Leads, not leads

Fields parameter is required for list operations (comma-separated, max 50 fields)

Supported Modules:

• Leads, Contacts, Accounts, Deals
• Campaigns, Tasks, Calls, Events, Products

Pro Tips

Tip 1: Multiple Zoho accounts? If you have multiple CRM connections, specify which one with the Maton-Connection header:

req.add_header("Maton-Connection", "your-connection-id")

Tip 2: Pagination for large datasets. For up to 2,000 records, use the page parameter. For larger datasets, use the page_token returned in the response:

req = urllib.request.Request(
    f"https://gateway.maton.ai/zoho-crm/crm/v8/Leads?fields=Last_Name&page_token={token}"
)

Tip 3: Use criteria search for complex queries:

import urllib.parse
criteria = urllib.parse.quote("(Last_Name:starts_with:Smith)and(Company:equals:Acme)")
url = f"https://gateway.maton.ai/zoho-crm/crm/v8/Leads/search?criteria={criteria}"

Tip 4: Check field names before building queries. Use the fields metadata endpoint:

Gotchas

• Empty results return HTTP 204 with no body—handle this gracefully
• Required fields vary by module (e.g., Deals need both Deal_Name and Stage)
• Max 100 records per create/update/delete request
• Max 200 records returned per GET request

Conclusion

The zoho-crm skill removes the biggest pain point of Zoho integration: OAuth token management. With Maton handling the authentication layer, your agent can focus on what matters—managing leads, closing deals, and keeping your CRM in sync with the rest of your workflow.

Links:

• Install from ClawdHub
• Zoho CRM API v8 Docs
• Maton Gateway

Happy CRM wrangling! 🎯