ハッカートラックとの統合を構築するためのパートナーガイド

Last updated: February 7, 2026

概要

このドキュメントは、HackerRank for Workとの統合を開発したいパートナー向けです。 私たちは常にATSベンダーと協力して、より良いユーザーエクスペリエンスのための統合を開発しています。このドキュメントは、あなた自身が統合を開発するために必要なすべての情報を提供します。

背景

私たちのエンタープライズ顧客の中には、HackerRank for Work TestsやInterviewsを評価段階で使用する顧客も含まれます。これらの顧客は、全体的な採用プロセスを管理するために他のITシステムも使用しています。これらのシステムは、Oracle Taleo、Jobvite、Greenhouse、Lever、Kenexa、RecruiterBoxなどの商用既製品（COTS）システム、またはカスタムの自家製システムのいずれかです。これらのアプリを総称して応募者追跡システム（ATS）と呼びます。

このような顧客は、ATSとHackerRank for Workとの間の統合を頻繁に求めています。これにより、候補者の管理に関するルーチン作業をATSのワークフロー内で行うことができます。これらのルーチン作業の例には、(a) 選考された候補者をHackerRank for Workのテストに招待する、(b) その候補者のテスト結果をATSで閲覧する、(c) エンジニアと選ばれた候補者の間でHackerRank面接セッションをスケジュールする、(d) ATSインターフェース内で面接レポートを閲覧するなどがあります。したがって、最も一般的に求められる統合ポイントは、既存のHackerRank for Workアカウントからデータを取得し、ATSインターフェース内から特定の操作を行うことです。これらの操作を実行するためのAPI呼び出しも用意しています。

一般的なワークフロー

この統合は、通常、HackerRank for Work APIを使用したプラグインまたはカスタマイズを通じてATSに機能を追加することによって行われます。これは、以下の図を用いて視覚的に最もよく説明されます。

以下のワークフローで使用される規則：

統合設定 - 一度だけの活動

注意：すべての公式ATS統合には、HackerRank for Work内にセクションがあり、各企業のアカウント管理者がキーを生成できるようになっています。あなたのATSは次の場所に表示されます：https://www.hackerrank.com/work/settings/api

全体のテストフロー

全体のCodePair（インタビューAPI）フロー

統合プロセス

無料トライアルに登録

こちらの https://www.hackerrank.com/work/signup にアクセスして、当社の製品の無料14日間トライアルにサインアップしてください。このアカウントは、API（下記参照）を探索し、統合をテストするために必要となります。

APIを探索する

私たちはシンプルなRESTful APIを提供しており、これが統合の基礎となります。こちらからAPIについて学び始めてください：

https://www.hackerrank.com/work/apidocs

注意：上記のドキュメントはエンドユーザーを念頭に置いて書かれています。テストアカウントでエンドユーザーとしてAPIを探索してください。APIについて質問がある場合は、HackerRankの担当者に連絡するか、support@hackerrank.com にサポートリクエストを送信してください。

統合の登録

APIに慣れ、サポートしたいフローをマッピングしたら、HackerRankの担当者に連絡するか、support@hackerrank.com に連絡してパートナーキーとシークレットトークンをリクエストしてください。また、統合に使用するための「企業全体のAPIキー」も発行されます。

統合コードの認証メカニズムを変更

3つの変更を行う必要があります：

カスタムヘッダーを追加「X-HRW-Partner-Authorization: abcd」ここでabcdはPartnerKey:PartnerSecretのBase64エンコードされたバージョンに置き換えてください。
カスタムヘッダーを追加「HRW-User-Email: user@email.com」ここでuser@email.comはリクエストを開始するユーザーのメールアドレスに置き換えてください。このメールアドレスは、顧客のHRWアカウントに既に存在するユーザーと一致する必要があります。
企業全体のAPIキーを使用 APIを探索したときに使用した個人アクセストークンの代わりに使用します。
すべての呼び出しにおいて、必要に応じて追加のメタデータを含めることもできます。HackerRankに保存してほしいメタデータがある場合です。一般的に見られるフィールドには以下があります：
user_emailはリクエストを開始するユーザーを識別します。これは、顧客のHRWアカウントに既に存在するユーザーと一致する必要があります。
candidateIdは、この候補者のシステム内の一意の識別子である場合があります。一部のAPI呼び出しは候補者固有ではなく、その場合はこのフィールドを無視できます。
applicationIdは、候補者が複数のReqに応募できる場合に使用できます。これは異なるフィールドであり、特定の申請を識別します。一部のAPI呼び出しは候補者固有ではなく、その場合はこのフィールドを無視できます。

{

...

"metadata": {

"candidateId": "16651587",

"applicationId": "25145412",

"user_email": "abcd@example.com"

}

パートナー認証トークンと企業ごとのキーを使用することは重要です。なぜなら、私たちは異なるポリシーとレート制限のセットを持っているからです。また、これにより、あなたから発生した顧客の問題をより簡単にトラブルシューティングでき、より良いユーザー体験につながります。

統合検証

上記のパートナー認証を使用するように統合を変更したら、正常なパスの評価と、過去に統合で遭遇したいくつかの既知のコーナーケースについて評価します。

エンドユーザードキュメントのレビューは、検証作業の重要な部分となります。

一般提供開始

検証が完了したら、すべてのサポートされている統合を表示するATS統合ページにエントリを追加します。そのインターフェースを使用して、一般の顧客は自分であなたの統合を有効または無効にすることができます。

あなたの統合は、私たちの統合設定ページのオプションとして利用可能になります：https://www.hackerrank.com/work/settings/api

統合のベストプラクティス

エラーシナリオ

ATSに関する私たちの経験では、候補者の招待に失敗する一般的なシナリオは次のとおりです：

APIキーがあなたのHackerRank for Workアカウントに対して無効です。（企業ごとのキーであり、パートナー認証が正しく機能している必要があります）
ATSアカウントのリクルーターのメールアドレス（メタデータ経由で送信される）が、HackerRank for Work内で使用されているメールアドレスと異なります（例：ATSアカウントでsriram.karra@hackerrank.comを使用し、HRWアカウントでsriram@hackerrank.comを使用）。どちらを修正しても構いませんが、同じである必要があります。
候補者のメールアドレスが欠落または無効です
このメールの候補者はすでに招待されています。
リクルーターはHackerRankに「採用席」を持っておらず、そのため候補者を招待する権限がありません
リクルーターは特定のテストにアクセスする権限がありません
リクルーターのHackerRankアカウントが有効化されていません。

上記のすべてのシナリオについて統合をテストし、アプリケーションの動作が円滑であることを確認することをお勧めします。

エラー処理

テストAPI

テストAPIでは、2つの異なる形式でエラーを返します。両方のレスポンス形式をカバーし、エンドユーザーに適切なメッセージを表示する必要があります。

ケース 1: エラーは候補者に限定されます。例えば、候補者に再招待する場合です。これは次の形式です：

{

"data": {

"username": “error@hackerrank.com",

"password": "96d3efe9",

"test_link": “link",

"status": false,

"error": 1002,

"error_message": "候補者はすでに同じテストに招待されています。再招待したい場合は、まずHackerRank for Workアカウントで招待をキャンセルしてください。"

"message": "招待された候補者はいません。",

}

太字のフィールドはエラーが発生したことを示しています。候補者の作成中に未捕捉のエラーがある場合も、この形式で表示されます。

ケース 2: リクルーターの設定自体にエラーがある場合（通常は設定ミスやフォーマットの誤りによるもの）、次の形式で返されます：

{

"data": {},

"status": false,

"message": "そのようなテストは存在しません",

}

このエラーを引き起こす操作には、無効なリクルーターアカウント、無効なメール、誤ったテストIDなどがあります。

成功したリクエストは200のレスポンスコードで返されます。

不正なアクセストークン: これら二つのエラーシナリオに加え、ユーザーが誤ったアクセスコードで統合を設定している場合、次の形式でエラーを返します。レスポンスコードは401です：

{

"model": {},

"message": "無効なアクセストークン"

}

CodePair API（インタビューAPI）

不正なアクセストークン: リクエストに含まれるアクセストークンが無効な場合、空のレスポンスと403のステータスコードを返します。

無効な情報: アクセストークンのエラー以外に1つ以上のエラーがある場合、すべてのエラーをerrorsフィールドにリストし、リクエストのステータスを422にします。例：

{

"errors": [

"タイトルは必須項目です",

"インタビューの時間範囲が無効です",

"......."

]

}