Maton

Zoho CRM

Access the Zoho CRM API with managed OAuth authentication. Manage leads, contacts, accounts, deals, and other CRM modules with full CRUD operations including search and bulk operations. Also supports organization details, user management, and module metadata retrieval.

Reference

Modules

Zoho CRM organizes data into modules. Core modules include:

ModuleAPI NameDescription
LeadsLeadsPotential customers
ContactsContactsIndividual people
AccountsAccountsOrganizations/companies
DealsDealsSales opportunities
CampaignsCampaignsMarketing campaigns
TasksTasksTo-do items
CallsCallsPhone call logs
EventsEventsCalendar appointments
ProductsProductsItems you sell

List Records

GET /zoho-crm/crm/v8/{module_api_name}?fields={field1},{field2}

Query Parameters:

ParameterTypeDescription
fieldsstringRequired. Comma-separated field API names (max 50)
pageintegerPage number (default: 1)
per_pageintegerRecords per page (default/max: 200)
sort_bystringSort by: id, Created_Time, or Modified_Time
sort_orderstringasc or desc (default)
cvidlongCustom view ID
page_tokenstringFor >2000 records pagination

Example - List Leads:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/Leads?fields=First_Name,Last_Name,Email,Phone,Company')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "data": [
    {
      "First_Name": "Christopher",
      "Email": "christopher-maclead@noemail.invalid",
      "Last_Name": "Maclead (Sample)",
      "Phone": "555-555-5555",
      "Company": "Rangoni Of Florence",
      "id": "7243485000000597000"
    }
  ],
  "info": {
    "per_page": 200,
    "count": 1,
    "page": 1,
    "sort_by": "id",
    "sort_order": "desc",
    "more_records": false,
    "next_page_token": null
  }
}

Example - List Contacts:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/Contacts?fields=First_Name,Last_Name,Email,Phone')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Example - List Accounts:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/Accounts?fields=Account_Name,Website,Phone')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Example - List Deals:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/Deals?fields=Deal_Name,Stage,Amount')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Record

GET /zoho-crm/crm/v8/{module_api_name}/{record_id}

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/Leads/7243485000000597000')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Records

POST /zoho-crm/crm/v8/{module_api_name}
Content-Type: application/json

{
  "data": [
    {
      "field_api_name": "value"
    }
  ]
}

Mandatory Fields by Module:

ModuleRequired Fields
LeadsLast_Name
ContactsLast_Name
AccountsAccount_Name
DealsDeal_Name, Stage
TasksSubject
CallsSubject, Call_Type, Call_Start_Time, Call_Duration
EventsEvent_Title, Start_DateTime, End_DateTime

Example - Create Lead:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "Last_Name": "Smith",
        "First_Name": "John",
        "Email": "john.smith@example.com",
        "Company": "Acme Corp",
        "Phone": "+1-555-0123"
    }]
}).encode()
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/Leads', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "data": [
    {
      "code": "SUCCESS",
      "details": {
        "Modified_Time": "2026-02-06T01:10:56-08:00",
        "Modified_By": {
          "name": "User Name",
          "id": "7243485000000590001"
        },
        "Created_Time": "2026-02-06T01:10:56-08:00",
        "id": "7243485000000619001",
        "Created_By": {
          "name": "User Name",
          "id": "7243485000000590001"
        }
      },
      "message": "record added",
      "status": "success"
    }
  ]
}

Example - Create Contact:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "Last_Name": "Doe",
        "First_Name": "Jane",
        "Email": "jane.doe@example.com",
        "Phone": "+1-555-9876"
    }]
}).encode()
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/Contacts', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Example - Create Account:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "Account_Name": "Acme Corporation",
        "Website": "https://acme.com",
        "Phone": "+1-555-1234"
    }]
}).encode()
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/Accounts', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Update Records

PUT /zoho-crm/crm/v8/{module_api_name}
Content-Type: application/json

{
  "data": [
    {
      "id": "record_id",
      "field_api_name": "updated_value"
    }
  ]
}

Example:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "id": "7243485000000619001",
        "Phone": "+1-555-9999",
        "Company": "Updated Company Name"
    }]
}).encode()
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/Leads', data=data, method='PUT')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "data": [
    {
      "code": "SUCCESS",
      "details": {
        "Modified_Time": "2026-02-06T01:11:01-08:00",
        "Modified_By": {
          "name": "User Name",
          "id": "7243485000000590001"
        },
        "Created_Time": "2026-02-06T01:10:56-08:00",
        "id": "7243485000000619001",
        "Created_By": {
          "name": "User Name",
          "id": "7243485000000590001"
        }
      },
      "message": "record updated",
      "status": "success"
    }
  ]
}

Delete Records

DELETE /zoho-crm/crm/v8/{module_api_name}?ids={record_id1},{record_id2}

Query Parameters:

ParameterTypeDescription
idsstringComma-separated record IDs (required, max 100)
wf_triggerbooleanExecute workflows (default: true)

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/Leads?ids=7243485000000619001', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "data": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "7243485000000619001"
      },
      "message": "record deleted",
      "status": "success"
    }
  ]
}

Search Records

GET /zoho-crm/crm/v8/{module_api_name}/search

Query Parameters (one required):

ParameterTypeDescription
criteriastringSearch criteria (e.g., (Last_Name:equals:Smith))
emailstringSearch by email address
phonestringSearch by phone number
wordstringGlobal text search
pageintegerPage number
per_pageintegerRecords per page (max 200)

Criteria Format: ((field_api_name:operator:value) and/or (...))

Operators:

  • Text fields: equals, not_equal, starts_with, in
  • Date/Number fields: equals, not_equal, greater_than, less_than, between, in
  • Boolean fields: equals, not_equal

Example - Search by email:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/Leads/search?email=christopher-maclead@noemail.invalid')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Example - Search by criteria:

python <<'EOF'
import urllib.request, os, json
import urllib.parse
criteria = urllib.parse.quote('(Last_Name:starts_with:Smith)')
req = urllib.request.Request(f'https://api.maton.ai/zoho-crm/crm/v8/Leads/search?criteria={criteria}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "data": [
    {
      "First_Name": "Christopher",
      "Email": "christopher-maclead@noemail.invalid",
      "Last_Name": "Maclead (Sample)",
      "id": "7243485000000597000"
    }
  ],
  "info": {
    "per_page": 200,
    "count": 1,
    "page": 1,
    "more_records": false
  }
}

Organization Details

Retrieve your Zoho CRM organization details.

GET /zoho-crm/crm/v8/org

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/org')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "org": [
    {
      "id": "7243485000000020005",
      "company_name": "Acme Corp",
      "domain_name": "org123456789",
      "primary_email": "admin@example.com",
      "phone": "555-555-5555",
      "currency": "US Dollar - USD",
      "currency_symbol": "$",
      "iso_code": "USD",
      "time_zone": "PST",
      "country_code": "US",
      "zgid": "123456789",
      "type": "production",
      "mc_status": false,
      "license_details": {
        "paid": true,
        "paid_type": "enterprise",
        "users_license_purchased": 10,
        "trial_expiry": null
      }
    }
  ]
}

Users

Retrieve users in your Zoho CRM organization.

GET /zoho-crm/crm/v8/users

Query Parameters:

ParameterTypeDescription
typestringFilter by user type: AllUsers, ActiveUsers, DeactiveUsers, ConfirmedUsers, NotConfirmedUsers, DeletedUsers, ActiveConfirmedUsers, AdminUsers, ActiveConfirmedAdmins, CurrentUser
pageintegerPage number (default: 1)
per_pageintegerRecords per page (default/max: 200)
idsstringComma-separated user IDs (max 100)

Example - List all users:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/users?type=AllUsers')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "users": [
    {
      "id": "7243485000000590001",
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "email": "john.doe@example.com",
      "status": "active",
      "confirm": true,
      "role": {
        "name": "CEO",
        "id": "7243485000000026005"
      },
      "profile": {
        "name": "Administrator",
        "id": "7243485000000026011"
      },
      "time_zone": "PST",
      "country": "US",
      "locale": "en_US"
    }
  ],
  "info": {
    "per_page": 200,
    "count": 1,
    "page": 1,
    "more_records": false
  }
}

Example - Get specific user:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/users/7243485000000590001')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Modules Metadata

Retrieve metadata about all available CRM modules.

GET /zoho-crm/crm/v8/settings/modules

Query Parameters:

ParameterTypeDescription
statusstringFilter by status: user_hidden, system_hidden, scheduled_for_deletion, visible

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/settings/modules')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "modules": [
    {
      "api_name": "Leads",
      "module_name": "Leads",
      "singular_label": "Lead",
      "plural_label": "Leads",
      "api_supported": true,
      "creatable": true,
      "editable": true,
      "deletable": true,
      "viewable": true,
      "status": "visible",
      "generated_type": "default",
      "id": "7243485000000002175",
      "profiles": [
        {"name": "Administrator", "id": "7243485000000026011"}
      ]
    }
  ]
}

Fields Metadata

Retrieve field metadata for a specific module.

GET /zoho-crm/crm/v8/settings/fields?module={module_api_name}

Query Parameters:

ParameterTypeDescription
modulestringRequired. API name of the module (e.g., Leads, Contacts)
typestringall for all fields, unused for unused fields only

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/settings/fields?module=Leads')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "fields": [
    {
      "api_name": "Last_Name",
      "field_label": "Last Name",
      "data_type": "text",
      "system_mandatory": true,
      "custom_field": false,
      "visible": true,
      "searchable": true,
      "sortable": true,
      "id": "7243485000000002613"
    }
  ]
}

Layouts Metadata

Retrieve layout metadata for a specific module.

GET /zoho-crm/crm/v8/settings/layouts?module={module_api_name}

Query Parameters:

ParameterTypeDescription
modulestringRequired. API name of the module (e.g., Leads, Contacts)

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/settings/layouts?module=Leads')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "layouts": [
    {
      "id": "7243485000000091055",
      "name": "Standard",
      "api_name": "Standard",
      "status": "active",
      "visible": true,
      "profiles": [
        {"name": "Administrator", "id": "7243485000000026011"}
      ],
      "sections": [
        {
          "display_label": "Lead Information",
          "api_name": "Lead_Information",
          "sequence_number": 1,
          "fields": [...]
        }
      ]
    }
  ]
}

Roles

Retrieve roles in your Zoho CRM organization.

GET /zoho-crm/crm/v8/settings/roles

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/settings/roles')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "roles": [
    {
      "id": "7243485000000026005",
      "name": "CEO",
      "display_label": "CEO",
      "share_with_peers": true,
      "description": null,
      "reporting_to": null
    },
    {
      "id": "7243485000000026008",
      "name": "Manager",
      "display_label": "Manager",
      "share_with_peers": false,
      "reporting_to": {
        "name": "CEO",
        "id": "7243485000000026005"
      }
    }
  ]
}

Example - Get specific role:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/settings/roles/7243485000000026005')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Profiles

Retrieve profiles (permission sets) in your Zoho CRM organization.

GET /zoho-crm/crm/v8/settings/profiles

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/settings/profiles')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "profiles": [
    {
      "id": "7243485000000026011",
      "name": "Administrator",
      "display_label": "Administrator",
      "type": "normal_profile",
      "custom": false,
      "description": null
    },
    {
      "id": "7243485000000026014",
      "name": "Standard",
      "display_label": "Standard",
      "type": "normal_profile",
      "custom": false,
      "description": null
    }
  ]
}

Example - Get specific profile:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-crm/crm/v8/settings/profiles/7243485000000026011')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Resources

PreviousZoho CalendarNextZoho Inventory

On this page

Reference
Modules
List Records
Get Record
Create Records
Update Records
Delete Records
Search Records
Organization Details
Users
Modules Metadata
Fields Metadata
Layouts Metadata
Roles
Profiles
Resources