Zoho CRM
管理されたOAuth認証でZoho CRM APIにアクセスします。リード、取引先担当者、顧客、商談、その他のCRMモジュールに対して、検索やバルク操作を含む完全なCRUD操作を実行できます。組織詳細、ユーザー管理、モジュールメタデータの取得もサポートしています。
クイックスタート
# リード一覧表示
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
ベースURL
https://gateway.maton.ai/zoho-crm/crm/v8/{endpoint}
ゲートウェイはリクエストを www.zohoapis.com/crm/v8 にプロキシし、OAuthトークンを自動的に注入します。
認証
すべてのリクエストには、Authorization ヘッダーに Maton API キーが必要です。
Authorization: Bearer $MATON_API_KEY
環境変数: APIキーを MATON_API_KEY として設定します。
export MATON_API_KEY="YOUR_API_KEY"
APIキーの取得
- maton.ai でサインインまたはアカウントを作成します。
- maton.ai/settings にアクセスします。
- APIキーをコピーします。
接続管理
Zoho CRM OAuth接続は https://ctrl.maton.ai で管理します。
接続一覧
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
接続作成
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
接続取得
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
レスポンス:
{
"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": {}
}
}
返された url をブラウザで開いてOAuth認証を完了します。
接続削除
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
接続の指定
複数のZoho CRM接続がある場合、Maton-Connection ヘッダーで使用する接続を指定します。
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
省略された場合、ゲートウェイはデフォルト(最も古い)のアクティブな接続を使用します。
APIリファレンス
モジュール
Zoho CRMはデータをモジュールに整理します。主要なモジュールは次のとおりです。
| モジュール | API名 | 説明 |
|---|---|---|
| リード | Leads | 見込み顧客 |
| 取引先担当者 | Contacts | 個人 |
| 顧客 | Accounts | 組織/企業 |
| 商談 | Deals | 販売機会 |
| キャンペーン | Campaigns | マーケティングキャンペーン |
| タスク | Tasks | やることリスト |
| 通話 | Calls | 通話ログ |
| イベント | Events | カレンダー予定 |
| 商品 | Products | 販売するアイテム |
レコード一覧
GET /zoho-crm/crm/v8/{module_api_name}?fields={field1},{field2}
クエリパラメータ:
| パラメータ | 型 | 説明 |
|---|---|---|
fields | string | 必須. カンマ区切りのフィールドAPI名(最大50) |
page | integer | ページ番号(デフォルト: 1) |
per_page | integer | 1ページあたりのレコード数(デフォルト/最大: 200) |
sort_by | string | 並び替え: id, Created_Time, Modified_Time |
sort_order | string | asc または desc(デフォルト) |
cvid | long | カスタムビューID |
page_token | string | 2000レコードを超えるページネーション用 |
例 - リード一覧:
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
レスポンス:
{
"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
}
}
例 - 取引先担当者一覧:
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
例 - 顧客一覧:
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
例 - 商談一覧:
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
レコード取得
GET /zoho-crm/crm/v8/{module_api_name}/{record_id}
例:
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
レコード作成
POST /zoho-crm/crm/v8/{module_api_name}
Content-Type: application/json
{
"data": [
{
"field_api_name": "value"
}
]
}
モジュール別必須フィールド:
| モジュール | 必須フィールド |
|---|---|
| リード | Last_Name |
| 取引先担当者 | Last_Name |
| 顧客 | Account_Name |
| 商談 | Deal_Name, Stage |
| タスク | Subject |
| 通話 | Subject, Call_Type, Call_Start_Time, Call_Duration |
| イベント | Event_Title, Start_DateTime, End_DateTime |
例 - リード作成:
python <<'EOF'
import urllib.request, os, json
data = json.dumps({
"data": [{
"Last_Name": "Smith",
"First_Name": "John",
"Email": "[email protected]",
"Company": "Acme Corp",
"Phone": "+1-555-0123"
}]
}).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
レスポンス:
{
"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"
}
]
}
例 - 取引先担当者作成:
python <<'EOF'
import urllib.request, os, json
data = json.dumps({
"data": [{
"Last_Name": "Doe",
"First_Name": "Jane",
"Email": "[email protected]",
"Phone": "+1-555-9876"
}]
}).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
例 - 顧客作成:
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://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
レコード更新
PUT /zoho-crm/crm/v8/{module_api_name}
Content-Type: application/json
{
"data": [
{
"id": "record_id",
"field_api_name": "updated_value"
}
]
}
例:
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://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
レスポンス:
{
"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 /zoho-crm/crm/v8/{module_api_name}?ids={record_id1},{record_id2}
クエリパラメータ:
| パラメータ | 型 | 説明 |
|---|---|---|
ids | string | カンマ区切りのレコードID(必須、最大100) |
wf_trigger | boolean | ワークフローを実行するかどうか(デフォルト: true) |
例:
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
レスポンス:
{
"data": [
{
"code": "SUCCESS",
"details": {
"id": "7243485000000619001"
},
"message": "record deleted",
"status": "success"
}
]
}
レコード検索
GET /zoho-crm/crm/v8/{module_api_name}/search
クエリパラメータ(いずれか必須):
| パラメータ | 型 | 説明 |
|---|---|---|
criteria | string | 検索条件(例: (Last_Name:equals:Smith)) |
email | string | メールアドレスで検索 |
phone | string | 電話番号で検索 |
word | string | 全体テキスト検索 |
page | integer | ページ番号 |
per_page | integer | 1ページあたりのレコード数(最大200) |
条件の書式: ((field_api_name:operator:value) and/or (...))
演算子:
- テキストフィールド:
equals,not_equal,starts_with,in - 日付/数値フィールド:
equals,not_equal,greater_than,less_than,between,in - ブールフィールド:
equals,not_equal
例 - メールで検索:
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
例 - 条件で検索:
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
レスポンス:
{
"data": [
{
"First_Name": "Christopher",
"Email": "[email protected]",
"Last_Name": "Maclead (Sample)",
"id": "7243485000000597000"
}
],
"info": {
"per_page": 200,
"count": 1,
"page": 1,
"more_records": false
}
}