プロダクト

採用プラットフォーム向けREST API：Bearerトークンパターンで実現する採用統合

ClarityHire Team(Editorial)2026-05-2110 min read

REST APIが必要な理由

ほとんどの最新ATS プラットフォームは、ウェブフックとネイティブUIを通じてのみデータを公開しています。組織が小さく、プロセスがシンプルなら問題ありません。しかし、以下のようなことを実現したい場合：

既存の統合がないHRシステム（BambooHR、Workday）に候補者情報を同期する
レポートをデータウェアハウスに取り込んでカスタム分析を行う
レガシーシステムから大量の候補者情報をインポートする
チームが好む独自のダッシュボードを構築する
ZapierやMake.comで自動化タスクを実行する（コード不要）

こうした要望に応えるには、公開REST APIが必須です。

REST APIはSaaS統合の標準言語です。HTTPでコミュニケーションを取るあらゆるツール（Zapier、Make、n8n、Pipedream、Pythonスクリプト、モバイルアプリ、カスタムダッシュボード）が、シンプルな認証トークンでデータを読み書きできます。

Bearerトークンパターン

セキュアなAPI認証の中でもっともシンプルなパターンがBearerトークンです。各ユーザーにAPIキーを発行し、Authorization: Bearer YOUR_KEYヘッダーに含めることで、すべてのリクエストがそのキーに対して認証されます。

Stripe、GitHub、Slack、そして最新のほとんどのAPIは、このパターンを採用しています。キーの無効化は簡単（削除するだけ）、ローテーションも簡単（新しいキーを生成）、スコープの設定も簡単（キーごとに異なる権限を付与）です。

curl -H "Authorization: Bearer sk_live_abc123xyz" \
  https://api.clarityhire.com/v1/candidates?job_id=j_engineering_2026

ユーザー名/パスワード認証やOAuthと比べて、Bearerトークンはステートレス（セッションデータベース不要）で、即座に無効化でき、どのキーがどのリクエストを行ったかを監査できます。

スコープと権限

セキュリティのベストプラクティスとして、トークンには「すべての機能への読み取り・書き込みアクセス」を与えるべきではありません。代わりにスコープを使い分けます。

candidates:read       # 候補者一覧の表示と詳細の確認
candidates:write      # 候補者の段階遷移、メモ追加
tests:read            # テスト結果の確認
tests:write           # テストの作成・編集
jobs:read             # 職務一覧の表示
webhooks:manage       # ウェブフックの作成・削除

サードパーティの開発者（例えば、あなたのプラットフォームと統合するHRISベンダー）がAPIアクセスをリクエストしてきた場合、candidates:readとcandidates:writeのみのトークンを発行します。請求データの閲覧や面接質問の変更はできません。

スコープは誤操作によるダメージも防ぎます。統合スクリプトにバグがあって候補者の削除を始めても、スクリプトがcandidates:readのみの権限であれば、問題を素早く検出できます。

ウェブフックとポーリング

データを同期させるための2つのパターンがあります。

ウェブフック（イベント駆動）：

POST https://your-system.com/webhook/clarityhire
{
  "event": "candidate.stage_changed",
  "data": {
    "candidate_id": "c_123",
    "old_stage": "screening",
    "new_stage": "assessment",
    "timestamp": "2026-05-21T14:30:00Z"
  }
}

ClarityHireで何か変化が起きると、あなたのエンドポイントにPOSTリクエストが送られます。リアルタイムで処理でき、効率的で、ポーリングのオーバーヘッドもありません。

ポーリング（プルベース）：

GET https://api.clarityhire.com/v1/candidates?job_id=j_123&updated_since=2026-05-21T00:00:00Z

定期的に（5分ごと、1時間ごとなど）ClarityHireに「何が変わったか？」と問い合わせて、レスポンスを処理します。HTTPエンドポイントを公開できないシステムの場合は実装が簡単ですが、遅延が生じ、APIへのリクエストも増えてしまいます。

ベストプラクティス： リアルタイム同期（段階の変更、新規応募）にはウェブフック、定期的なバッチ処理（毎日すべての候補者をデータウェアハウスにエクスポート）にはポーリングを使い分けてください。

いずれのパターンもリトライロジックをサポートする必要があります。ウェブフックは失敗することがあります（ネットワーク障害、エンドポイントのダウンタイム）。APIは指数バックオフでリトライを試みるべきで、失敗した配信を「ウェブフックログ」ダッシュボードで確認できるようにします。

レート制限と冪等性

APIを公開する際は、悪用と誤った重複登録を防ぐセーフガードが必要です。

レート制限： 「APIキーあたり、1時間に1,000リクエストまで」といった制限を設けます。上限を超えた場合、Retry-Afterヘッダー付きで429レスポンスを返します。ZapierなどのAPIプラットフォームは、これらの制限を自動的に認識し、尊重します。

冪等性： ウェブフック配信が失敗してリトライする場合を考えます。しかし、リクエストは実際には成功していたものの、レスポンスがタイムアウトしたらどうなるか？冪等性がないと、候補者が二重登録されたり、段階遷移が二重実行されたりします。

解決策は、書き込みリクエストでIdempotency-Keyヘッダーを必須にすることです。

curl -H "Authorization: Bearer sk_live_abc123xyz" \
  -H "Idempotency-Key: zap_12345_attempt_1" \
  -X POST https://api.clarityhire.com/v1/candidates \
  -d '{"email": "[email protected]", "job_id": "j_eng"}'

APIはこのキーとそのレスポンスを保存します。同じキーでリクエストが再度送信されれば、キャッシュされたレスポンスが返されます。重複は発生しません。

ドキュメントとSDK

APIは詳細なドキュメントがないと、誰も使えません。以下が不可欠です。

エンドポイントリファレンス： すべてのエンドポイント、全パラメータ、レスポンス形式を網羅
エラーコード： 400や403が何を意味するのか、明確な説明
ウェブフックイベントタイプ： 配信されるイベントの完全なリスト、サンプルペイロード
コード例： curl、Python、JavaScriptによるよくあるタスクのサンプル
認証ガイド： APIキーの生成・ローテーション方法

さらに、Python、JavaScript、Goといった一般的な言語のSDKを公開することで、導入をさらに促進できます。Zapier向けには組み込みSDKがありますが、カスタム統合はページネーション、リトライ、エラーハンドリングを自動化するネイティブクライアントライブラリから大きく利益を得ます。

Zapier統合：次元の違う活用

Zapierは数百のアプリをコード不要で連携させるプラットフォームです。REST APIを公開すると、カスタム統合を1本ずつ開発する（4週間）のではなく、Zapier連携を1～2週間で構築できるようになります。

Zapierの活用例：

トリガー： 「ClarityHireの『シニアバックエンドエンジニア』職務に新規候補者が追加された」
アクション1： 「Google Sheetsに行を追加」
アクション2： 「#hiring チャンネルにSlackメッセージを送信」
アクション3： 「Pipedrive に連絡先を作成」

Zapierユーザーの1人がコード不要でこれを設定します。他のZapierユーザーはZapierマーケットプレイスでこの組み合わせを発見し、採用します。あなたのチームが1本の統合コードも書かないまま、100もの統合シナリオが成立するエコシステムが形成されます。

ClarityHireのAPI実装方法

ClarityHireは/api/v1/*エンドポイントをBearerトークン認証、スコープベースの権限管理、ウェブフックサポート付きで提供しています。リファレンスドキュメントはapi.clarityhire.com/docsにあります。レート制限はAPIキーあたり1時間に1,000リクエスト。書き込みリクエストはIdempotency-Keyヘッダーで冪等性を確保します。

主なエンドポイント：

GET /api/v1/candidates — 候補者一覧（フィルタリング、ページネーション対応）
GET /api/v1/candidates/{id} — 単一候補者の詳細
POST /api/v1/candidates/{id}/move-stage — 段階の遷移
GET /api/v1/webhooks — アクティブなウェブフック一覧
POST /api/v1/webhooks — 新規ウェブフック登録

ウェブフックはイベントタイプ、job_id、オーガナイゼーション単位でフィルタリング可能です。配信失敗時は24時間のうちに指数バックオフで10回までリトライします。

まとめ

公開REST API + Bearerトークンは、統合の扉を大きく開きます。使用シーンに応じてスコープを使い分け。リアルタイム同期はウェブフック、バッチ処理はポーリングを選択。書き込みの冪等性を強制して重複を防止。エラーコードと実装例を含めて十分ドキュメント化。そしてZapier統合は、あなたのチームがコードを書かずに1,000の活用シーンを実現させる強力な増幅装置になります。

API設計への投資は、柔軟性と導入の加速という形で大きなリターンをもたらします。

API統合Zapierウェブフック採用自動化