HERP Hireは日本の主要な採用管理システム(ATS)の1つで、約30の求人媒体との連携と豊富なAPIを特徴とする。本記事では、HERP Hire APIを自社システムに統合する本番実装パターンを、renueが実装している`HerpHireClient`クラスをもとに解説する。Bearer認証・ページネーション対応・SSL検証切替・AI採用分析への接続まで、本番運用で押さえるべき設計を網羅する。
HERP Hire API統合の基礎
HERP Hireは約30の求人媒体と連携可能なATSで、API経由でHERPからデータを取得したり、HERPへのデータ登録・更新ができる。自社システムから採用データを活用したい場合、以下のユースケースが典型である。
- 独自ダッシュボード構築: HERPの標準画面では表示しきれない分析軸を追加
- AI採用分析との連携: 候補者データをAIに渡して適合度スコアリング
- SlackやTeamsへの自動通知: 応募があれば担当者にリアルタイム通知
- 既存人事システムとの連携: SmartHR等へのオンボーディング手続き自動化
- 独自レポート自動生成: 週次/月次の採用KPIレポート
HERP Hire APIの基本仕様
| 項目 | 仕様 |
|---|---|
| ベースURL | https://public-api.herp.cloud/hire/v1 |
| 認証方式 | Bearer Token(APIキー) |
| 主要エンドポイント | /candidacies(応募)、/requisitions(求人)、/members(担当者) |
| ページネーション | hasNextPageフラグ方式 |
| レスポンス形式 | JSON(camelCase) |
| 日付形式 | YYYY-MM-DD または ISO 8601 |
| レート制限 | 公式ドキュメントに従う |
本番品質のHERP統合に必要な6レイヤー
レイヤー1: Bearer認証の設計
HERP Hire APIはBearer認証を採用している。APIキーの管理は他のAPI統合と同様、環境変数経由が原則である。
class HerpHireClient:
def __init__(self, api_key=None):
self.api_key = api_key or env_setting.HERP_HIRE_API_KEY
if not self.api_key:
raise ValueError("HERP_HIRE_API_KEY environment variable is not set")
self.base_url = "https://public-api.herp.cloud/hire/v1"
# SSL検証: LOCAL環境では無効化、それ以外は有効
self.verify_ssl = env_setting.PY_ENV != "LOCAL"
def _get_headers(self):
return {
"Authorization": f"Bearer {self.api_key}",
"Content-Type": "application/json",
}
起動時チェックの重要性
APIキーが未設定の状態で初期化すると`ValueError`を投げる。これは本番運用で重要なfail-fastパターンである。
- 起動時に設定ミスを即座に検出
- リクエスト時のエラーより早期に発見
- デプロイ直後の動作確認で気付ける
- サイレントな失敗を防ぐ
レイヤー2: SSL検証の環境別切替
renueの実装では`PY_ENV`環境変数でSSL検証を切り替えている。
self.verify_ssl = env_setting.PY_ENV != "LOCAL"
LOCAL環境でSSLを無効化する理由
- 開発用プロキシを経由する場合(Charles Proxy等)
- 自己署名証明書を使うテスト環境
- ネットワーク制約が厳しい環境での開発
本番では必須
本番・ステージング環境では必ずSSL検証を有効にする。無効化するとMITM攻撃のリスクがある。この切替をフラグ1つで管理することで、開発体験と本番セキュリティを両立できる。
レイヤー3: ページネーション対応
HERP Hire APIは`hasNextPage`フラグ方式のページネーションを採用している。候補者が多いクライアントでは1ページに収まらないことが多いため、全ページ取得が必須である。
APIレスポンス形式
{
"candidacies": [
{
"id": "string",
"name": "string",
"status": "active",
"requisitionId": "string",
"appliedAt": "2019-08-24T14:15:22Z",
"step": "entry",
...
}
],
"hasNextPage": true
}
全ページ自動取得の実装
def get_candidacies(
self,
status=None,
requisition_id=None,
step=None,
appliedAtFrom=None,
appliedAtTo=None,
fetch_all_pages=True,
max_pages=None,
**kwargs,
):
url = f"{self.base_url}/candidacies"
headers = self._get_headers()
params = {}
if status:
params["status"] = status
if requisition_id:
params["requisitionId"] = requisition_id # HERP API uses camelCase
if appliedAtFrom:
params["appliedAtFrom"] = appliedAtFrom
if appliedAtTo:
params["appliedAtTo"] = appliedAtTo
params.update(kwargs)
all_candidacies = []
page = 1
max_pages_limit = max_pages if max_pages is not None else 1000 # 無限ループ防止
# ...
無限ループ防止ガード
重要な安全対策が`max_pages_limit`である。`max_pages=None`でも1000ページを上限とすることで、APIバグや想定外のレスポンスで無限ループになるリスクを排除する。
fetch_all_pages フラグの使い分け
- fetch_all_pages=True(デフォルト): 全ページ取得。集計や分析用途
- fetch_all_pages=False: 最初の1ページのみ。画面の先頭表示用途
レイヤー4: 命名規則の対応(camelCase vs snake_case)
HERP Hire APIはJavaScript的なcamelCase命名である(`requisitionId`, `appliedAtFrom`等)。一方、Pythonコードはsnake_caseが標準。この不整合をどう扱うかが設計のポイントになる。
パラメータ名の扱い方針
# Python関数の引数はsnake_caseで受ける
def get_candidacies(
self,
requisition_id=None,
appliedAtFrom=None, # ← 意図的にcamelCaseのまま受ける
):
params = {}
if requisition_id:
params["requisitionId"] = requisition_id # snake_case → camelCase変換
if appliedAtFrom:
params["appliedAtFrom"] = appliedAtFrom # そのままパススルー
renueの実装では、APIパラメータと同じ名前を使う場合(`appliedAtFrom`)は、Pythonの引数もcamelCaseのまま受ける折衷案を採用している。変換層が1箇所で済み、呼び出し側もHERP APIドキュメントを見ながらコードを書きやすい。
2つの戦略の比較
| 戦略 | メリット | デメリット |
|---|---|---|
| 完全snake_case変換 | Python的に綺麗 | 全パラメータの変換が必要 |
| 選択的camelCase維持 | APIドキュメントと一致 | 規約の一貫性が崩れる |
チームの方針やコードレビューの基準に応じて選択する。renueは後者の実用的パターンを採用している。
レイヤー5: フィルタパラメータの活用
HERP Hire APIは豊富なフィルタパラメータを提供する。本番運用では以下を活用する。
主要フィルタパラメータ(動作確認済み)
- status: active / rejected / withdrew 等でステータス絞り込み
- requisitionId: 求人ID(特定職種の候補者のみ)
- step: entry / screening / interview 等の選考ステップ
- appliedAtFrom / appliedAtTo: 応募日の範囲
- stepUpdatedAtFrom / stepUpdatedAtTo: 選考ステップ更新日の範囲
実務上のクエリパターン
- 今月の新規応募: `appliedAtFrom=月初`
- 先週進捗があった候補者: `stepUpdatedAtFrom=7日前`
- 特定職種の一次面接待ち: `requisitionId=X, step=interview_1st`
- アクティブな全候補者: `status=active`
レイヤー6: AI採用分析との連携
HERPからデータを取得しただけでは価値は生まれない。AI採用分析と連携して以下を自動化する。
AI連携の典型パターン
- 候補者スコアリング: 履歴書情報をLLMに渡して適合度を算出
- 離脱予測: ステップが長期間停滞している候補者を自動検知
- 書類チェック自動化: 履歴書から要件に合致しない候補者を除外
- 面接サマリー生成: 議事録AIとの連携で面接内容を自動要約
- スカウト文面生成: 候補者属性に合わせたパーソナライズド文面
データフローの設計
[HERP Hire]
↓ HerpHireClient.get_candidacies
[自社DB(候補者マスタ)]
↓ AI分析エンジン(LLM)
[スコアリング / 要約 / 推薦]
↓ 通知エンジン
[Slack / Email / 独自ダッシュボード]
ポーリング戦略
HERPからのデータ同期はWebhookではなくポーリング方式になる。頻度の設計が重要。
ポーリング頻度の推奨
- 15分間隔: 緊急性の高い新規応募通知
- 1時間間隔: 通常のダッシュボード更新
- 日次: 統計レポート用のフル同期
- イベント駆動: Slackコマンドでオンデマンド実行
差分同期の実装
全件取得はコストが高い。`stepUpdatedAtFrom`を前回実行時刻に設定することで、更新された候補者のみを取得する差分同期が可能である。
エラーハンドリング
HERP APIとの通信では以下のエラーに対処する必要がある。
- 401 Unauthorized: APIキー無効(fail-fast+通知)
- 403 Forbidden: 権限不足(権限設定を確認)
- 404 Not Found: 指定IDが存在しない
- 429 Too Many Requests: レート制限(指数バックオフでリトライ)
- 500 Server Error: HERP側の問題(短時間後リトライ)
- timeout: ネットワーク遅延(3回までリトライ)
データ保護の留意点
候補者データは極めて機密性の高い個人情報である。以下の対策が必須。
必須のセキュリティ対策
- アクセス制御: 採用担当者のみデータにアクセス可
- ログ記録: 誰が何のデータを見たかを完全記録
- 暗号化: DBに保存する際は個人情報を暗号化
- 保持期間: 不合格候補者のデータは一定期間後に削除
- GDPR/APPI対応: 候補者からの削除要求に対応
- LLMへの送信: 氏名・連絡先は匿名化してから送信
匿名化の実装例
LLMに候補者情報を渡す際、以下を匿名化する。
- 氏名 → 「候補者A」
- メールアドレス → 削除
- 電話番号 → 削除
- 住所 → 都道府県レベルのみ
- 前職企業名 → 業種のみ(任意)
スキル・職歴・志望動機などはそのまま渡す。これにより個人特定されずに適合度分析ができる。
HERP Hire以外のATSへの応用
この設計パターンは他のATSにも応用可能である。
| ATS | API認証方式 | 特徴 |
|---|---|---|
| HERP Hire | Bearer Token | 国内ATS、30媒体連携 |
| SmartHR採用管理 | OAuth 2.0 | SmartHRとのシームレス統合 |
| Sonar ATS | Bearer Token | 新卒採用特化 |
| ジョブカン採用管理 | APIキー | ジョブカングループ連携 |
| Workday | OAuth 2.0 | グローバル大企業向け |
| Greenhouse | Basic Auth | 米国系テック企業標準 |
共通するのは「認証 → フィルタ → ページネーション取得 → 差分同期」のパターン。renueの`HerpHireClient`設計は他ATSにも応用できる。
renueの実装特徴
renueは「Self-DX First」の方針のもと、HERP Hire統合を自社プロダクトとして実装している。社内12業務を553のAIツールで自動化済み(2026年1月時点)であり、採用業務もその一環として自動化が進んでいる(全て公開情報)。
技術スタック
- 言語: Python 3.11
- HTTPクライアント: requests
- ロギング: api_logger(HERP API専用logger)
- 認証: Bearer Token(環境変数)
- SSL検証: 環境別切替
- ページネーション: hasNextPage方式対応
- 最大取得上限: 1000ページ
導入時のよくある失敗パターン
- APIキーチェックを起動時に行わない: 運用開始後にエラー
- 全ページ取得を忘れる: 100件以降のデータが取れない
- 無限ループ防止ガードがない: APIバグで大量リクエスト発生
- camelCase/snake_caseの混在で混乱: パラメータ渡し間違い
- SSL検証を本番で無効化: セキュリティリスク
- 差分同期なしの全件取得: 毎回膨大なリクエスト
- 候補者情報をそのままLLMに送信: プライバシー違反
- エラー時の通知がない: 採用活動が止まっていることに気付けない
業界別の活用パターン
| 業界 | 活用パターン |
|---|---|
| SaaS/IT | エンジニア候補者のスキル自動分析、GitHub連携 |
| コンサル | 職歴からの適合度スコアリング、面接質問生成 |
| メーカー | 専門分野マッチング、勤務地最適化 |
| 小売・サービス | 大量応募のスクリーニング自動化 |
| 金融 | コンプライアンスチェック、資格確認 |
| 医療 | 免許情報の確認、シフト適合性分析 |
よくある質問
HERP Hire APIの利用料金は?
HERP Hireの契約プランに含まれている(プランによって利用可否が異なる)。追加料金なしでAPIを使える場合が多い。最新の料金情報は公式サイトで確認すること。
レート制限はどれくらい?
公式ドキュメントに従う必要がある。本番運用では余裕を持たせて1分あたり数十リクエスト程度に抑えるのが安全。差分同期を活用してリクエスト数を最小化する。
Webhookは使える?
2026年4月時点ではポーリング方式が主流。Webhookが提供されている場合でも、データ保護の観点からポーリング+差分同期の組み合わせが本番運用では推奨される。
候補者情報をLLMに渡しても良い?
個人情報を匿名化してから渡すのが原則。氏名・連絡先・住所(都道府県以外)は削除または仮名化する。LLMプロバイダーはEnterpriseプラン(データを学習に使わない)を選ぶ。
導入後に最も改善するKPIは?
「書類選考の時間」と「候補者への初回返信までの時間」が最も改善する。AIスコアリングで優先度が明確になるため、重要候補者へのアプローチが早くなる。結果として優秀な候補者の獲得率が向上する。