Zoho CRM

Greifen Sie über die Zoho CRM API mit verwalteter OAuth-Authentifizierung zu. Verwalten Sie Leads, Kontakte, Firmen, Deals und andere CRM-Module mit vollständigen CRUD-Operationen, einschließlich Suche und Bulk-Operationen. Unterstützt werden auch Organisationsdetails, Benutzerverwaltung und das Abrufen von Modul-Metadaten.

Schnellstart

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

Basis-URL

https://gateway.maton.ai/zoho-crm/crm/v8/{endpoint}

Das Gateway leitet Anfragen an www.zohoapis.com/crm/v8 weiter und fügt automatisch Ihr OAuth-Token ein.

Authentifizierung

Alle Anfragen benötigen den Maton-API-Key im Authorization-Header:

Authorization: Bearer $MATON_API_KEY

Umgebungsvariable: Setzen Sie Ihren API-Key als MATON_API_KEY:

export MATON_API_KEY="IHR_API_KEY"

So erhalten Sie Ihren API-Key

Melden Sie sich an oder erstellen Sie ein Konto unter maton.ai
Gehen Sie zu maton.ai/settings
Kopieren Sie Ihren API-Key

Verbindungsverwaltung

Verwalten Sie Ihre Zoho CRM OAuth-Verbindungen unter https://ctrl.maton.ai.

Verbindungen auflisten

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

Verbindung erstellen

python <<'EOF'
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')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Verbindung abrufen

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

Antwort:

{
  "connection": {
    "connection_id": "e55c5bac-241a-4cc8-9db5-50d2cad09136",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "zoho-crm",
    "metadata": {}
  }
}

Öffnen Sie die zurückgegebene url in einem Browser, um die OAuth-Autorisierung abzuschließen.

Verbindung löschen

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', 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

Verbindung festlegen

Wenn Sie mehrere Zoho CRM-Verbindungen haben, legen Sie die zu verwendende mit dem Header Maton-Connection fest:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/zoho-crm/crm/v8/Leads?fields=First_Name,Last_Name,Email')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', 'e55c5bac-241a-4cc8-9db5-50d2cad09136')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Wenn nicht angegeben, verwendet das Gateway die Standardverbindung (älteste aktive).

API-Referenz

Module

Zoho CRM organisiert Daten in Modulen. Zu den Kernmodulen gehören:

Modul	API-Name	Beschreibung
Leads	`Leads`	Potenzielle Kunden
Kontakte	`Contacts`	Einzelpersonen
Firmen	`Accounts`	Organisationen/Unternehmen
Deals	`Deals`	Vertriebschancen
Kampagnen	`Campaigns`	Marketingkampagnen
Aufgaben	`Tasks`	Aufgaben
Anrufe	`Calls`	Telefonanrufprotokolle
Ereignisse	`Events`	Kalendereinträge
Produkte	`Products`	Von Ihnen verkaufte Artikel

Datensätze auflisten

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

Abfrageparameter:

Parameter	Typ	Beschreibung
`fields`	string	Erforderlich. Kommagetrennte Feld-API-Namen (max. 50)
`page`	integer	Seitennummer (Standard: 1)
`per_page`	integer	Datensätze pro Seite (Standard/Max: 200)
`sort_by`	string	Sortieren nach: `id`, `Created_Time` oder `Modified_Time`
`sort_order`	string	`asc` oder `desc` (Standard)
`cvid`	long	Benutzerdefinierte Ansichts-ID
`page_token`	string	Für Seitennummerierung >2000 Datensätze

Beispiel – Leads auflisten:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.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

Antwort:

{
  "data": [
    {
      "First_Name": "Christopher",
      "Email": "[email protected]",
      "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
  }
}

Beispiel – Kontakte auflisten:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.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

Beispiel – Firmen auflisten:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.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

Beispiel – Deals auflisten:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.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

Datensatz abrufen

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

Beispiel:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.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

Datensätze erstellen

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

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

Pflichtfelder nach Modul:

Modul	Erforderliche Felder
Leads	`Last_Name`
Kontakte	`Last_Name`
Firmen	`Account_Name`
Deals	`Deal_Name`, `Stage`
Aufgaben	`Subject`
Anrufe	`Subject`, `Call_Type`, `Call_Start_Time`, `Call_Duration`
Ereignisse	`Event_Title`, `Start_DateTime`, `End_DateTime`

Beispiel – Lead erstellen:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "Last_Name": "Smith",
        "First_Name": "John",
        "Email": "[email protected]",
        "Company": "Acme GmbH",
        "Phone": "+49-30-12345678"
    }]
}).encode()
req = urllib.request.Request('https://gateway.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

Antwort:

{
  "data": [
    {
      "code": "SUCCESS",
      "details": {
        "Modified_Time": "2026-02-06T01:10:56-08:00",
        "Modified_By": {
          "name": "Benutzername",
          "id": "7243485000000590001"
        },
        "Created_Time": "2026-02-06T01:10:56-08:00",
        "id": "7243485000000619001",
        "Created_By": {
          "name": "Benutzername",
          "id": "7243485000000590001"
        }
      },
      "message": "Datensatz hinzugefügt",
      "status": "success"
    }
  ]
}

Beispiel – Kontakt erstellen:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "Last_Name": "Doe",
        "First_Name": "Jane",
        "Email": "[email protected]",
        "Phone": "+49-30-98765432"
    }]
}).encode()
req = urllib.request.Request('https://gateway.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

Beispiel – Konto erstellen:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "Account_Name": "Acme GmbH",
        "Website": "https://acme.de",
        "Phone": "+49-30-12345678"
    }]
}).encode()
req = urllib.request.Request('https://gateway.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

Datensätze aktualisieren

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

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

Beispiel:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "data": [{
        "id": "7243485000000619001",
        "Phone": "+49-30-99999999",
        "Company": "Aktualisierter Firmenname"
    }]
}).encode()
req = urllib.request.Request('https://gateway.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

Antwort:

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

Datensätze löschen

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

Abfrageparameter:

Parameter	Typ	Beschreibung
`ids`	string	Kommagetrennte Datensatz-IDs (erforderlich, max. 100)
`wf_trigger`	boolean	Workflows ausführen (Standard: true)

Beispiel:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.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

Antwort:

{
  "data": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "7243485000000619001"
      },
      "message": "Datensatz gelöscht",
      "status": "success"
    }
  ]
}

Datensätze suchen

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

Abfrageparameter (einer erforderlich):

Parameter	Typ	Beschreibung
`criteria`	string	Suchkriterien (z. B. `(Last_Name:equals:Smith)`)
`email`	string	Nach E-Mail-Adresse suchen
`phone`	string	Nach Telefonnummer suchen
`word`	string	Volltextsuche
`page`	integer	Seitennummer
`per_page`	integer	Datensätze pro Seite (max. 200)

Kriterienformat: ((field_api_name:operator:value) and/or (...))

Operatoren:

Textfelder: equals, not_equal, starts_with, in
Datums-/Zahlenfelder: equals, not_equal, greater_than, less_than, between, in
Boolesche Felder: equals, not_equal

Beispiel – Suche nach E-Mail:

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

Beispiel – Suche nach Kriterien:

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://gateway.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

Antwort:

{
  "data": [
    {
      "First_Name": "Christopher",
      "Email": "[email protected]",
      "Last_Name": "Maclead (Sample)",
      "id": "7243485000000597000"
    }
  ],
  "info": {
    "per_page": 200,
    "count": 1,
    "page": 1,
    "more_records": false
  }
}

Organisationsdetails

GET /zoho-crm/crm/v8/org

Benutzerverwaltung

Benutzer auflisten

GET /zoho-crm/crm/v8/users?type={type}

Abfrageparameter:

Parameter	Typ	Beschreibung
`type`	string	Benutzertyp: `ActiveUsers`, `ActiveConfirmedUsers`, `CurrentUser`, `DeactiveUsers`, `AdminUsers`, `AllUsers` (Standard)

Beispiel – Aktive Benutzer auflisten:

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

Module und Felder

Module auflisten

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

Beispiel:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.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

Moduldetails

GET /zoho-crm/crm/v8/settings/modules/{module_api_name}

Beispiel – Leads-Moduldetails:

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

Fehlerbehandlung

Statuscodes

Code	Beschreibung
`SUCCESS`	Anfrage erfolgreich
`INVALID_DATA`	Ungültige oder fehlende Felder
`AUTHORIZATION_ERROR`	Ungültige oder abgelaufene OAuth- oder API-Key-Autorisierung – erneute Autorisierung erforderlich
`MANDATORY_NOT_FOUND`	Erforderliches Feld fehlt
`INTERNAL_ERROR`	Zoho-Serverfehler – Wiederholungsstrategie implementieren
`RATE_LIMIT_EXCEEDED`	Ratenlimit überschritten – Abklingzeit abwarten
`DUPLICATE_DATA`	Datensatz mit denselben Werten eines eindeutigen Feldes vorhanden

Wiederholungsstrategie

Verwenden Sie exponentielles Backoff für Fehler. Beispiel für einen Wiederholungsmechanismus in Python:

import urllib.request, os, json, time

def request_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        try:
            req = urllib.request.Request(url)
            req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
            return json.load(urllib.request.urlopen(req))
        except urllib.error.HTTPError as e:
            if e.code in [429, 500, 502, 503]:
                time.sleep(2 ** attempt)
                continue
            raise
        except Exception:
            raise
    return None

Limiten

Ratenlimit: 250 Anfragen pro Minute pro API-Key; bei Überschreitung Fehler RATE_LIMIT_EXCEEDED – warten Sie mindestens 60 Sekunden.
Maximale Batch-Größe: 100 Datensätze pro Anfrage für Create/Update.
Feldbegrenzung: Maximal 50 Felder in fields-Parameter.
Suchpaginierung: Maximal 200 Datensätze pro Seite.
Anfrage-Timeout: 120 Sekunden; übergreifen Sie lange laufende Bulk-Vorgänge in separate Hintergrundaufgaben.
Zeitzonen: Datums-/Uhrzeitangaben werden von Zoho in der Organisationszeitzone zurückgegeben.

Fehlerbehebung bei Autorisierung

API-Key und Verbindung überprüfen:

python -c "import os; print('API Key vorhanden' if os.environ.get('MATON_API_KEY') else 'API Key fehlt')"

Verbindungsstatus prüfen:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request(f'https://ctrl.maton.ai/connections?app=zoho-crm')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
connections = json.load(urllib.request.urlopen(req))['connections']
print(f"Verbindungen: {len(connections)}")
for c in connections:
    print(f"  - {c['connection_id']}: {c['status']}")
EOF

OAuth erneut autorisieren:

python <<'EOF'
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(f"Öffnen Sie zur Autorisierung: {result['connection']['url']}")
EOF

In Ihrer bevorzugten KI fragen

Dokumentation

Zoho CRM

Schnellstart

Basis-URL

Authentifizierung

So erhalten Sie Ihren API-Key

Verbindungsverwaltung

Verbindungen auflisten

Verbindung erstellen

Verbindung abrufen

Verbindung löschen

Verbindung festlegen

API-Referenz

Module

Datensätze auflisten

Datensatz abrufen

Datensätze erstellen

Datensätze aktualisieren

Datensätze löschen

Datensätze suchen

Organisationsdetails

Benutzerverwaltung

Benutzer auflisten

Module und Felder

Module auflisten

Moduldetails

Fehlerbehandlung

Statuscodes

Wiederholungsstrategie

Limiten

Fehlerbehebung bei Autorisierung

Individual skills in this repo

CraftOS-dev/CraftBot

CraftOS-dev/CraftBot

Verwandte Skills

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me