プロダクト

採用REST API：採用統合向けのBearerトークンパターン

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

REST API が必要な理由

ほとんどの最新ATS プラットフォームはウェブフックと基本 UI 経由でのみデータを公開します。20人と単一プロセスがある場合、これは機能します。しかし、あなたが望む瞬間に：

候補者を HR システム（BambooHR、Workday）に同期。事前構築統合がない
レポートをデータウェアハウスにプルしてカスタム分析を行う
古いシステムから候補者をバルクインポート
チームが基本 UI より優先するカスタムダッシュボードを構築
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       # ウェブフックを作成/削除

サードパーティー開発者が API アクセスを要求（例：プラットフォームと統合している HRIS プロバイダー）、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 で何かが起こると、エンドポイントに投稿します。すぐにそれを処理します。速い、効率的、ポーリングオーバーヘッドなし。

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

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 キー当たり1時間に1,000リクエストを行うことができます。」超える場合、 Retry-After ヘッダー付きで 429 応答を取得。Zapier と他の統合プラットフォームはこれらの制限を自動的に尊重。

冪等性： ウェブフック配信が失敗、リトライします。しかし、リクエストが実際に成功しましたが、応答がタイムアウトしました？冪等性なしで、重複候補を作成するか、候補を2回移動させます。

解決：書き込みリクエストで 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 スニペット
認証： キーを生成・回転させる方法

ボーナス：一般的な言語（Python、JavaScript、Go）の SDK を公開します。Zapier は組み込み SDK を備えていますが、カスタム統合は pagination、リトライ、エラー処理を処理するネイティブクライアントライブラリから恩恵を受けます。

Zapier 統合：次のレベルのレバレッジ

Zapier は数百のアプリをコードなしで接続。REST API を公開すると、Zapier 統合を書くことはカスタムビルドの代わりに 4週間で 1～2週間プロジェクトになります。

Zapier の例：

トリガー： 「ClarityHire 職務『シニアバックエンドエンジニア』の新しい候補者」
アクション 1： 「Google シートに行を追加」
アクション 2： 「Slack メッセージを #hiring に送信」
アクション 3： 「Pipedrive で連絡先を作成」

1つの Zapier ユーザーはこれをコードなしで設定。他の Zapier ユーザーは Zapier マーケットプレイスで見つけ採用。100個の統合を構築せずに 100統合エコシステムを作成しました。

ClarityHire が API を公開する方法

ClarityHire は Bearer トークン認証、スコープ権限、ウェブフックサポート付きで /api/v1/* を提供。参照ドキュメント api.clarityhire.com/docs に生きています。レート制限：キー当たり1時間に 1,000リクエスト。Idempotency-Key ヘッダー付き冪等な書き込み。

例エンドポイント：

GET /api/v1/candidates — 候補者をリスト（フィルタリング、pagination をサポート）
GET /api/v1/candidates/{id} — 単一候補者
POST /api/v1/candidates/{id}/move-stage — ステージトランジション
GET /api/v1/webhooks — アクティブなウェブフックをリスト
POST /api/v1/webhooks — 新しいウェブフックを登録

ウェブフックはイベントタイプ、job_id、またはオーガナイゼーションでフィルター。システムは24時間にわたって指数バックオフで10回失敗した配信をリトライします。

まとめ

Bearer トークン付き公開REST API がアンロックを統合。使用ケースで権限をスコープ。リアルタイム同期のウェブフックを優先、バッチエクスポートはポーリング。重複を防ぐため書き込みで冪等性を強制。エラーコードと例を含めて彼らに文書化。Zapier 統合は乗数：1つの API はチームをコーディングせずに 1,000の使用ケースを有効。

API デザインへの投資はフレキシビリティと採用で配当を支払います。

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