大規模なユーザーアカウントの管理は、最初は単純ですが、すぐに複雑になるタスクの1つです。新規買収からの顧客のオンボーディング、内部データベースからのユーザーの同期、またはセルフサービス登録フローの構築など、最終的にはZendesk（ゼンデスク）ユーザーをプログラムで作成する必要があります。
Zendesk Users API は、これを行うためのツールを提供します。これは、個々のユーザーの作成から、一度に数千人を一括インポートするまですべてを処理するRESTful（レストフル） APIです。このガイドでは、実際に動作させるための実践的な手順を、スタックに適応できる動作するコード例とともに説明します。
ユーザーの作成だけでなく、より多くのことを自動化したい場合は、eesel AI のようなツールを使用すると、チケットのルーティングからAI（人工知能）による応答まで、サポート自動化の全範囲を処理できます。
必要なもの
API（エーピーアイ）呼び出しを開始する前に、以下を確認してください。
- 管理者アクセス権を持つZendeskアカウント 管理者のみがAPIトークンを作成し、API経由でユーザーを管理できます。
- APIトークンまたはOAuth（オーオース）認証情報 これらを生成する方法については後述します。
- REST API（レストエーピーアイ）の基本的な知識 POST（ポスト）リクエストとは何かを知っておく必要があります。
- 開発環境 cURL（カール）、Python（パイソン）、またはNode.js（ノードジェイエス）で問題ありません。
ステップ1：API認証の設定
Zendesk（ゼンデスク）は、APIアクセス用にAPIトークンとOAuth（オーオース）の2つの主要な認証方法をサポートしています。ほとんどのサーバー間統合では、APIトークンの方が実装が簡単です。
APIトークンの生成
- 管理者としてZendesk（ゼンデスク）アカウントにサインインします。
- 管理センターに移動します（歯車アイコンをクリックし、「管理センターに移動」をクリックします）。
- アプリと連携機能 → API → Zendesk APIに移動します。
- 設定タブをクリックし、トークンアクセスが有効になっていることを確認します。
- APIトークンタブに切り替え、APIトークンを追加をクリックします。
- 「User Sync Integration（ユーザー同期連携）」のようなわかりやすい名前を入力します。
- トークンをすぐにコピーします Zendesk（ゼンデスク）は一度しか表示しません。
認証ヘッダーのフォーマット
Zendesk（ゼンデスク）は、APIトークンでBasic（ベーシック）認証を使用します。形式は次のとおりです。
- ユーザー名:
/tokenが付加されたZendesk（ゼンデスク）のメールアドレス（例：you@company.com/token） - パスワード: APIトークン自体
これらの認証情報をBase64（ベース64）でエンコードし、Authorization（オーソリゼーション）ヘッダーに含めます。
curl https://your-subdomain.zendesk.com/api/v2/users.json \
-u you@company.com/token:your_api_token_here
またはPython（パイソン）で：
import requests
from requests.auth import HTTPBasicAuth
subdomain = "your-subdomain"
email = "you@company.com"
token = "your_api_token_here"
auth = HTTPBasicAuth(f"{email}/token", token)
headers = {"Content-Type": "application/json"}
url = f"https://{subdomain}.zendesk.com/api/v2/users.json"
response = requests.get(url, auth=auth, headers=headers)
print(response.json())
セキュリティのベストプラクティス
- APIトークンを環境変数に保存し、コードには絶対に保存しないでください。
- トークンを定期的にローテーションします 古いものを削除し、新しいものを生成します。
- 各トークンが何に使用されるかを把握できるように、わかりやすいトークン名を使用します。
- 連携機能が廃止されたら、トークンを削除します。
- 管理者のトークンを使用するのではなく、制限された権限を持つ専用のサービスユーザーを作成することを検討してください。
ステップ2：単一のユーザーを作成する
ユーザーを作成する最も簡単な方法は、POST /api/v2/usersエンドポイントを使用することです。少なくとも、名前を提供する必要があります。
必須およびオプションのパラメーター
| パラメータ | 必須 | 説明 |
|---|---|---|
name | はい | ユーザーのフルネーム |
email | いいえ | プライマリメールアドレス（アイデンティティを作成） |
role | いいえ | end-user（デフォルト）、agent、またはadmin |
organization_id | いいえ | 割り当てる組織のID |
external_id | いいえ | このユーザーのシステムの一意の識別子 |
verified | いいえ | メール検証をスキップするには、trueに設定します |
ユーザーロールについて
Zendesk（ゼンデスク）には、3つの組み込みロールがあります。
- end-user: チケットを送信する顧客（ロールが指定されていない場合のデフォルト）
- agent: チケットを処理するサポートスタッフ
- admin: 完全な管理アクセス
Enterprise（エンタープライズ）プランの場合、custom_role_idパラメーターを使用して、カスタムエージェントロールを割り当てることもできます。カスタムロールは、最初に管理センターで作成する必要があることに注意してください API経由で作成することはできません。
コード例
cURL（カール）：
curl https://your-subdomain.zendesk.com/api/v2/users.json \
-d '{"user": {"name": "Jane Smith", "email": "jane@example.com", "role": "end-user"}}' \
-H "Content-Type: application/json" \
-X POST \
-u you@company.com/token:your_api_token
Python（パイソン）：
import requests
import json
from requests.auth import HTTPBasicAuth
subdomain = "your-subdomain"
auth = HTTPBasicAuth("you@company.com/token", "your_api_token")
headers = {"Content-Type": "application/json"}
user_data = {
"user": {
"name": "Jane Smith",
"email": "jane@example.com",
"role": "end-user",
"external_id": "user_12345"
}
}
response = requests.post(
f"https://{subdomain}.zendesk.com/api/v2/users.json",
auth=auth,
headers=headers,
json=user_data
)
if response.status_code == 201:
user = response.json()["user"]
print(f"Created user {user['id']}: {user['name']}")
else:
print(f"Error: {response.status_code} - {response.text}")
JavaScript（ジャバスクリプト）（Node.js（ノードジェイエス）とaxios（アクシオス）を使用）：
const axios = require('axios');
const subdomain = 'your-subdomain';
const email = 'you@company.com';
const token = 'your_api_token';
const userData = {
user: {
name: 'Jane Smith',
email: 'jane@example.com',
role: 'end-user',
external_id: 'user_12345'
}
};
axios.post(
`https://${subdomain}.zendesk.com/api/v2/users.json`,
userData,
{
auth: {
username: `${email}/token`,
password: token
},
headers: {
'Content-Type': 'application/json'
}
}
)
.then(response => {
const user = response.data.user;
console.log(`Created user ${user.id}: ${user.name}`);
})
.catch(error => {
console.error('Error:', error.response?.data || error.message);
});
レスポンスの解釈
作成が成功すると、ユーザーオブジェクトとともにHTTP 201 Created（作成済み）が返されます。
{
"user": {
"id": 9873843,
"name": "Jane Smith",
"email": "jane@example.com",
"role": "end-user",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"active": true,
"verified": false
}
}
ステップ3：ユーザーの作成または更新（アップサート）
すでに存在するユーザーを作成しようとするとどうなりますか？標準の作成エンドポイントは422エラーを返します。外部システムから定期的にユーザーをインポートする同期シナリオでは、代わりにcreate_or_updateエンドポイントを使用します。
create_or_updateを使用する場合
以下の場合にPOST /api/v2/users/create_or_updateを使用します。
- 外部データベースからユーザーを同期している場合
- べき等な操作（同じリクエストで同じ結果が生成される）が必要な場合
- 作成前にユーザーが存在するかどうかを確認したくない場合
マッチングの仕組み
Zendesk（ゼンデスク）は、以下によってユーザーを照合します。
- 外部ID 提供されている場合、これが優先されます。
- メールアドレス 外部IDの一致が見つからない場合
レスポンスコード
| ステータス | 意味 |
|---|---|
| 201 Created | 新しいユーザーが作成されました |
| 200 OK | 既存のユーザーが更新されました |
実践的な例：外部システムからの同期
import requests
from requests.auth import HTTPBasicAuth
auth = HTTPBasicAuth("you@company.com/token", "your_api_token")
headers = {"Content-Type": "application/json"}
external_users = [
{"name": "Jane Smith", "email": "jane@example.com", "external_id": "usr_001"},
{"name": "John Doe", "email": "john@example.com", "external_id": "usr_002"}
]
for external_user in external_users:
user_data = {"user": external_user}
response = requests.post(
"https://your-subdomain.zendesk.com/api/v2/users/create_or_update.json",
auth=auth,
headers=headers,
json=user_data
)
if response.status_code == 201:
print(f"Created: {external_user['email']}")
elif response.status_code == 200:
print(f"Updated: {external_user['email']}")
else:
print(f"Failed: {external_user['email']} - {response.text}")
ステップ4：複数のユーザーを一括で作成する
数百または数千のユーザーを作成する必要がある場合、個々のAPI（エーピーアイ）呼び出しは非効率的です。Zendesk（ゼンデスク）は、リクエストごとに最大100人のユーザーを受け入れる一括エンドポイントを提供します。
エンドポイントと制限
- エンドポイント:
POST /api/v2/users/create_many - 制限: リクエストごとに100人のユーザー
- 有効化: 一括インポートはZendesk（ゼンデスク）サポートによって有効にする必要があります（403エラーが発生した場合は、サポートに連絡してください）。
job_statusレスポンスについて
単一ユーザーの作成とは異なり、一括操作は非同期です。API（エーピーアイ）はjob_statusオブジェクトですぐに応答し、実際の作成はバックグラウンドで行われます。
{
"job_status": {
"id": "82de0b044094f0c67893ac9fe64f1a99",
"status": "queued",
"total": 50,
"progress": 0,
"url": "https://your-subdomain.zendesk.com/api/v2/job_statuses/82de0b044094f0c67893ac9fe64f1a99"
}
}
ジョブステータスURL（ユーアールエル）をポーリングして、進行状況を追跡します。
def check_job_status(job_url):
response = requests.get(job_url, auth=auth)
job = response.json()["job_status"]
print(f"Status: {job['status']}, Progress: {job['progress']}/{job['total']}")
if job["status"] == "completed":
for result in job.get("results", []):
print(f" {result['action']}: User {result['id']} - {result['status']}")
return job["status"]
import time
while check_job_status(job_url) != "completed":
time.sleep(5)
一括処理が理にかなっている場合
| シナリオ | アプローチ |
|---|---|
| 1〜50人のユーザー | 個々のAPI（エーピーアイ）呼び出し |
| 50〜10,000人のユーザー | バッチ処理による一括API（エーピーアイ） |
| 10,000人以上のユーザー | インポート支援についてはZendesk（ゼンデスク）にお問い合わせください |
一括作成の例
users_to_create = [
{"name": "User One", "email": "user1@example.com", "role": "end-user"},
{"name": "User Two", "email": "user2@example.com", "role": "end-user"},
# ... 最大100人のユーザー
]
response = requests.post(
"https://your-subdomain.zendesk.com/api/v2/users/create_many.json",
auth=auth,
headers=headers,
json={"users": users_to_create}
)
if response.status_code == 200:
job = response.json()["job_status"]
print(f"Job queued: {job['id']}")
else:
print(f"Error: {response.status_code} - {response.text}")
一般的なエラーとトラブルシューティング
適切なコードを使用しても、問題が発生する可能性があります。最も一般的な問題の処理方法を次に示します。
401 Unauthorized（認証されていません）
認証情報が無効です。確認してください：
- メールアドレスは正しいですか？
- ユーザー名に
/tokenを追加しましたか？ - API（エーピーアイ）トークンはまだアクティブですか（削除されていませんか）？
- 正しいサブドメインを使用していますか？
403 Forbidden（禁止）
このアクションを実行する権限がありません。一般的な原因：
- API（エーピーアイ）トークンは管理者ではなく、エージェントに属しています。
- 一括インポートがアカウントで有効になっていません（Zendesk（ゼンデスク）サポートにお問い合わせください）。
- 十分な権限なしに管理者ユーザーを作成しようとしています。
422 Unprocessable Entity（処理できないエンティティ）
リクエストデータが無効です。確認してください：
nameフィールドは存在しますか？（必須です）- メール形式は有効ですか？
- ロールは
end-user、agent、adminのいずれかですか？ - organization_idは存在しますか？
429 Too Many Requests（リクエストが多すぎます）
Zendesk（ゼンデスク）のレート制限に達しました。API（エーピーアイ）は、待機する秒数を示すRetry-Afterヘッダーを返します。コードに指数バックオフを実装します。
import time
def api_call_with_retry(url, auth, headers, json_data, max_retries=3):
for attempt in range(max_retries):
response = requests.post(url, auth=auth, headers=headers, json=json_data)
if response.status_code == 429:
retry_after = int(response.headers.get('Retry-After', 60))
print(f"Rate limited. Waiting {retry_after} seconds...")
time.sleep(retry_after)
continue
return response
raise Exception("Max retries exceeded")
重複するメールエラー
「メールアドレスはすでに使用されています」という422エラーが表示された場合は、次のいずれかを行います。
- 代わりに
create_or_updateエンドポイントを使用します。 - 最初に
GET /api/v2/users/search?query=email@example.comでユーザーが存在するかどうかを確認します。
ユーザー管理自動化のベストプラクティス
Zendesk Users API（ゼンデスクユーザーAPI）を使用した後、一貫してうまく機能するパターンを次に示します。
べき等性にはexternal_idを使用する
常に、内部ユーザーID（アイディー）にマッピングするexternal_idを含めます。これにより、操作がべき等になり、同期が簡素化されます。
user_data = {
"user": {
"name": "Jane Smith",
"email": "jane@example.com",
"external_id": f"internal_db_{internal_user_id}"
}
}
確認ステータスを設定してメール確認をスキップする
信頼できるソース（独自のデータベースなど）からユーザーを作成する場合は、verified: trueを設定して、Zendesk（ゼンデスク）が確認メールを送信しないようにします。
user_data = {
"user": {
"name": "Jane Smith",
"email": "jane@example.com",
"verified": True # 確認メールをスキップ
}
}
カスタムロールを正しく処理する
カスタムロールはEnterprise（エンタープライズ）機能です。割り当てるには：
- 最初に管理センターでカスタムロールを作成します。
- ロールのURL（ユーアールエル）またはAPI（エーピーアイ）から
custom_role_idを取得します。 role: "agent"とcustom_role_id: 12345の両方を設定します。
適切なエラー処理を実装する
API（エーピーアイ）呼び出しが成功することを前提としないでください。呼び出しをtry/except（トライ/エクセプト）ブロックでラップし、特定のエラーケースを処理します。
try:
response = requests.post(url, auth=auth, headers=headers, json=data)
response.raise_for_status()
except requests.exceptions.HTTPError as e:
if response.status_code == 422:
errors = response.json().get("details", {})
print(f"Validation error: {errors}")
else:
raise
認証情報を安全に保存する
API（エーピーアイ）トークンをハードコードしないでください。環境変数を使用します。
import os
ZENDESK_SUBDOMAIN = os.environ.get("ZENDESK_SUBDOMAIN")
ZENDESK_EMAIL = os.environ.get("ZENDESK_EMAIL")
ZENDESK_TOKEN = os.environ.get("ZENDESK_TOKEN")
より広範な自動化のニーズを検討する
ユーザーの作成を自動化している場合は、サポート業務の拡大を管理している可能性があります。Zendesk API（ゼンデスクAPI）はユーザー管理を処理しますが、チケットの処理、ルーティング、および応答も自動化する必要がある場合があります。eesel AI はZendesk（ゼンデスク）と統合して、チケットの分類とタグ付けからAI（人工知能）による応答の作成まで、これらのワークフローを自動的に処理します。
Zendesk（ゼンデスク）ワークフローの自動化を開始する
これで、Zendesk（ゼンデスク）ユーザーをプログラムで作成するための基盤ができました。ユーザー同期連携の構築、オンボーディングの自動化、大規模な顧客ベースの管理など、Users API（ユーザーAPI）は必要な制御を提供します。
このガイドのパターン 認証、単一作成、アップサート、および一括操作 は、ほとんどの現実世界のシナリオをカバーしています。セットアップを検証するには、単一ユーザーのエンドポイントから開始し、スケールが増加したら一括操作に移行します。
ユーザーの作成を超えて自動化したい場合は、AI（人工知能）がサポートワークフロー全体をどのように合理化できるかを検討してください。eesel AI はZendesk（ゼンデスク）と統合して、チケットのトリアージ、応答の作成、インテリジェントなルーティングを処理し、手作業を減らしながら応答時間を改善します。カスタマーサービス向けのAIエージェント を調べて、自動化がサポートスタック全体にどのように拡張できるかを確認できます。
よくある質問
この記事を共有
Article by
Stevia Putri
Stevia Putri is a marketing generalist at eesel AI, where she helps turn powerful AI tools into stories that resonate. She’s driven by curiosity, clarity, and the human side of technology.
