API docs by Redocly

HERP Hire API ドキュメント (1.5.0)

Download OpenAPI specification:Download

HERP Hire APIの利用について

本APIは有料プランのお客様のみ利用可能です。

有料プランへのアップグレード希望の場合は、サービス上の問い合わせフォームよりご連絡ください。

APIキーの発行

HERP Hire APIを利用する人はAPIキーを発行する必要があります。

HERP Hireの画面の右上のメニューから「APIキー」を選択して、指示に従ってAPIキーを発行してください。

APIキーは管理者権限を持つユーザーのみが発行・確認できます。

発行されたAPIキーを Authorization: Bearer ヘッダーに付加してリクエストを送信してください。

アクセス制限

HERP HireではAPIアクセスを テナントごと に1分間100リクエストまでに制限しています。

APIのレスポンスヘッダーには以下のアクセス情報が付加されます。

x-remaining-request: 99 # 期間内にリクエストできる残りの回数
x-reset-at: 2025-03-24T00:00:00+09:00    # 残り回数がリセットされる時刻

ステータスコード

レスポンスのステータスコードは以下のように解釈されます。

ステータスコード 説明
200 正常なレスポンス
400 パラメーターに不備があった
401 認証に失敗した
403 アクセス権限がない
404 存在しないリソースにアクセスした
429 アクセス回数が制限を超えた
500 サーバー側で予期しないエラーが発生した

リソースIDの取得

各リソースのIDは以下の方法で取得できます。

リソース IDの取得方法
応募ID 個別の応募ページのURLの/id/以降の36文字
応募情報CSVや集計用データ > 応募でも確認可能
職種ID 個別の職種の編集ページのURLの/id/と/basicの間の36文字
集計用データ > 職種でも確認可能
職種グループID 個別の職種グループの編集ページのURLの/id/と/editの間の36文字
集計用データ > 職種グループ紐づけでも確認可能
ユーザーID 管理画面のメンバー管理ページでアカウントごとに記載されているU-xxxxx
集計用データ > ユーザーデータでも確認可能

応募にファイルを追加する

個別の応募情報にファイルを追加することができます。下記ご留意ください。
・一つのフィールドに対して複数ファイルを添付できる
・ファイルの形式は white list に含まれるもののみ許可
・アップロードするファイルの合計サイズは 50MB 以下

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ write
・ candidacy:all
・ candidacy:write

path Parameters
candidacyId
required
string

応募のID

Request Body schema: multipart/form-data
resumes
string <binary>

履歴書

careerSummaries
string <binary>

職務経歴書

otherFiles
string <binary>

その他の添付ファイル

Responses

Response samples

Content type
application/json
{
  • "result": "success"
}

応募ファイルのメタデータ一覧を取得する

応募に紐づく添付ファイルのメタデータを返すAPIです。

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ read
・ candidacy:all
・ candidacy:read

path Parameters
candidacyId
required
string

応募ID

Responses

Response samples

Content type
application/json
{
  • "files": [
    ]
}

応募ファイルのバイナリデータを取得する

応募ファイルのIDから、ファイルのバイナリデータを取得します。ファイルIDは応募ファイルのメタデータ一覧を取得するAPI(GET /v1/candidacies/{candidacyId}/files)経由で確認できます。

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ read
・ candidacy:all
・ candidacy:read

path Parameters
candidacyId
required
string

応募ID

fileId
required
string

ファイルID

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

応募を追加する

応募を追加することができます。下記ご留意ください。
・追加された応募の経路が手動追加になる
・選考ステップはエントリーになる

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ write
・ candidacy:all
・ candidacy:write

Request Body schema: application/json
required
object

応募経路

requisitionId
required
string

応募先の職種ID

appliedAt
string <date-time>

応募日時、指定しない場合は応募追加時の日時が設定されます
YYYY-MM-DDTHH:MM:SS±hh:mm の形式で指定してください

name
required
string <= 200 characters

応募者の氏名

email
string <email>

応募者のメールアドレス

telephoneNumber
string <= 20 characters

応募者の電話番号

currentCompany
string <= 255 characters

応募者の現所属

age
string <= 8 characters

応募者の年齢

education
string <= 200 characters

応募者の最終学歴

career
string <= 10000 characters

応募者の経歴

links
Array of strings <uri> <= 10 items [ items <uri > <= 255 characters ]

関連リンク

note
string <= 1500 characters

メモ

Responses

Request samples

Content type
application/json
{
  • "channel": {
    },
  • "requisitionId": "string",
  • "appliedAt": "2017-03-24T00:00:00+09:00",
  • "name": "string",
  • "email": "user@example.com",
  • "telephoneNumber": "string",
  • "currentCompany": "string",
  • "age": "string",
  • "education": "string",
  • "career": "string",
  • "links": [],
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "id": "string"
}

応募一覧を取得する

応募一覧を取得することができます。下記の条件を指定することで絞り込むことが可能です。

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ read
・ candidacy:all
・ candidacy:read

query Parameters
status
string
Enum: "active" "terminated"

応募の状態を指定して検索できます

値意味
active選考中
terminated選考終了
指定しない場合は全ての状態の応募を含みます

page
string

ページ番号を指定できます
1ページあたり100件の応募を取得します
指定しない場合は1ページ目を取得します

sort
string
Default: "appliedAt"
Enum: "appliedAt" "stepUpdatedAt"

応募をソートする項目を指定できます

値意味
appliedAt応募日
stepUpdatedAt選考ステップ更新日
指定しない場合は応募日でソートされます

direction
string
Default: "desc"
Enum: "asc" "desc"

ソートする際の順序を指定できます

値意味
asc昇順
desc降順
指定しない場合は降順でソートされます

appliedAtFrom
string

応募日の範囲検索の開始日
YYYY-MM-DD の形式で、日本時間で指定してください

appliedAtTo
string

応募日の範囲検索の終了日
YYYY-MM-DD の形式で、日本時間で指定してください

stepUpdatedAtFrom
string

選考ステップ更新日の範囲検索の開始日
YYYY-MM-DD の形式で、日本時間で指定してください

stepUpdatedAtTo
string

選考ステップ更新日の範囲検索の終了日
YYYY-MM-DD の形式で、日本時間で指定してください

requisitionId
string

職種IDを指定して応募を検索できます

step
string
Enum: "entry" "casualInterview" "resumeScreening" "firstInterview" "secondInterview" "thirdInterview" "finalInterview" "offered" "offerAccepted"

選考ステップを指定して応募を検索できます

値意味
entryエントリー
casualInterviewカジュアル面談
resumeScreening書類選考
firstInterview一次選考
secondInterview二次選考
thirdInterview三次選考
finalInterview最終選考
offered内定
offerAccepted内定承諾
※三次面接と内定承諾は、該当機能が有効になっているテナントのみで使用可能

terminationReason
string
Enum: "hired" "refusedByCandidate" "rejected" "notEligible"

選考終了理由を指定して応募を検索できます

値意味
hired入社決定
refusedByCandidate応募者辞退
rejected不採用
notEligible非選考対象

Responses

Response samples

Content type
application/json
{
  • "candidacies": [
    ],
  • "hasNextPage": true
}

応募に紐づくコンタクト一覧を取得する

応募に紐づくコンタクトを一覧で取得します。

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ read
・ candidacy:all
・ candidacy:read

path Parameters
candidacyId
required
string

応募ID

Responses

Response samples

Content type
application/json
{
  • "contacts": [
    ]
}

応募のコンタクトを作成する

応募に対してコンタクトを作成し、オプションで選考予定の作成・調整、評価依頼を同時に行うことができます。

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ write
・ candidacy:all
・ candidacy:write

path Parameters
candidacyId
required
string

応募のID

Request Body schema: application/json
createBy
required
string

コンタクト作成者のユーザーID
アシスタント以上の権限を持つユーザーである必要があります

required
object

コンタクトの基本情報

予定作成 (object) or 日程提案 (object) or 日程調整 (object)

コンタクトに紐づく選考予定を作成できます

object

コンタクトに紐づく評価依頼を作成できます

Responses

Request samples

Content type
application/json
{
  • "createBy": "string",
  • "contact": {
    },
  • "assessmentSchedule": {
    },
  • "evaluation": {
    }
}

Response samples

Content type
application/json
{
  • "contactId": "string",
  • "assessmentScheduleId": "string",
  • "appointmentSchedulingUrl": "string",
  • "googleMeetingUrl": "string",
  • "evaluationRequestIds": [
    ],
  • "errors": [
    ]
}

応募のタイムラインにコメントを追加する

応募のタイムラインにコメントを追加することができます。

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ write
・ candidacy:all
・ candidacy:write

path Parameters
candidacyId
required
string

応募のID

Request Body schema: application/json
mentionTo
Array of strings

メンションを送るユーザーのIDの配列

body
required
string <= 20000 characters

コメントの本文

textType
string
Enum: "text/plain" "text/markdown"

コメントの本文のテキストタイプを指定できます

値意味
text/plainプレーンテキスト
text/markdownマークダウン
指定されない場合は、プレーンテキストとして表示されます

Responses

Request samples

Content type
application/json
{
  • "mentionTo": [
    ],
  • "body": "string",
  • "textType": "text/plain"
}

Response samples

Content type
application/json
{
  • "id": "string"
}

応募のタイムラインコメントを取得する

応募のタイムラインコメントを取得することができます。

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ read
・ candidacy:all
・ candidacy:read

path Parameters
candidacyId
required
string

応募のID

Responses

Response samples

Content type
application/json
{
  • "comments": [
    ]
}

応募の詳細情報を取得する

個別の応募情報に対して応募一覧に含まれていない情報も取得することができます。

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ read
・ candidacy:all
・ candidacy:read

path Parameters
candidacyId
required
string

応募のID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "status": "active",
  • "requisitionId": "string",
  • "appliedAt": "2019-08-24T14:15:22Z",
  • "step": "entry",
  • "email": "string",
  • "telephoneNumber": "string",
  • "age": "string",
  • "company": "string",
  • "channel": {
    },
  • "education": "string",
  • "career": "string",
  • "note": "string",
  • "links": [
    ],
  • "operators": [
    ],
  • "recommendationFromAgent": "string",
  • "agentEmailAddress": {
    },
  • "messageToCompany": "string",
  • "terminationReason": "hired",
  • "terminatedAt": "2019-08-24T14:15:22Z",
  • "stepUpdatedAt": "2019-08-24T14:15:22Z"
}

応募の選考ステップを更新する

応募の選考ステップを更新することができます。

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ write
・ candidacy:all
・ candidacy:write

path Parameters
candidacyId
required
string

応募のID

Request Body schema: application/json
step
required
string
Enum: "entry" "casualInterview" "resumeScreening" "firstInterview" "secondInterview" "thirdInterview" "finalInterview" "offered" "offerAccepted"

応募の選考ステップ

値意味
entryエントリー
casualInterviewカジュアル面談
resumeScreening書類選考
firstInterview一次選考
secondInterview二次選考
thirdInterview三次選考
finalInterview最終選考
offered内定
offerAccepted内定承諾
※三次面接と内定承諾は、該当機能が有効になっているテナントのみで使用可能

Responses

Request samples

Content type
application/json
{
  • "step": "entry"
}

Response samples

Content type
application/json
{
  • "id": "string"
}

評価の詳細情報を取得する

コンタクトに紐づく評価の詳細情報を取得します。
評価者、評価日時、評価フォーム、回答内容などが含まれます。

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ read
・ candidacy:all
・ candidacy:read

path Parameters
evaluationRequestId
required
string

評価依頼のID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "candidacyId": "string",
  • "contactId": "string",
  • "requesterId": "string",
  • "evaluatorId": "string",
  • "requestedAt": "2025-10-16T10:00:00+09:00",
  • "note": "string",
  • "status": "completed",
  • "completedAt": "2025-10-16T10:00:00+09:00",
  • "editedAt": "2025-10-16T10:00:00+09:00",
  • "declineReason": "評価する時間が取れないため",
  • "evaluationForm": {
    }
}

評価を記入・更新する

評価依頼に対して回答を記入または更新します。
評価未記入の場合は新規記入、評価記入済みの場合は上書き更新となります。

バリデーションルール

項目ルール
必須項目必ず回答する必要があります
任意項目項目ごと省略、または空白な配列を指定することができます
自由記述式文字列1つのみ（配列の要素数は1）
単一選択式選択肢の中から1つのみ（配列の要素数は1）
複数選択式選択肢の中から複数（配列の要素数は1以上）

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ write
・ candidacy:all
・ candidacy:write
path Parameters
evaluationRequestId
required
string

評価依頼のID

Request Body schema: application/json
required
Array of objects
textType
string
Default: "text/plain"
Enum: "text/plain" "text/markdown"

コメントの本文のテキストタイプを指定できます。

値意味
text/plainプレーンテキスト
text/markdownマークダウン
指定されない場合は、プレーンテキストとして表示されます

Responses

Request samples

Content type
application/json
{
  • "answers": [
    ],
  • "textType": "text/markdown"
}

Response samples

Content type
application/json
{
  • "evaluationRequestId": "string",
  • "evaluationResultId": "string"
}

職種一覧を取得する

職種一覧を取得することができます。
下記の条件を指定することで絞り込むことが可能です。

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ read
・ requisition:all
・ requisition:read

query Parameters
status
string
Enum: "active" "archived"

職種の状態を指定して検索できます

値意味
activeアクティブな職種
archivedアーカイブされた職種
指定しない場合は全ての状態の職種を含みます

careerPageStatus
string
Enum: "published" "unlisted" "private"

職種求人ページの公開状態を指定して検索できます

値意味
published公開中
unlisted限定公開中
private非公開
指定しない場合は全てのステータスの職種を含みます

page
string

ページ番号を指定できます
1ページあたり100件の職種を取得します
指定しない場合は1ページ目を取得します

sort
string
Default: "createdAt"
Enum: "createdAt" "updatedAt"

職種をソートする項目を指定できます

値意味
createdAt作成日時
updatedAt更新日時
指定しない場合は作成日時でソートされます

direction
string
Default: "desc"
Enum: "asc" "desc"

ソートする際の順序を指定できます

値意味
asc昇順
desc降順
指定しない場合は降順でソートされます

Responses

Response samples

Content type
application/json
{
  • "requisitions": [
    ],
  • "hasNextPage": true
}

職種グループの詳細を取得する

職種グループの詳細を取得することができます。

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ read
・ requisition:all
・ requisition:read

path Parameters
requisitionGroupId
required
string

職種グループのID

Responses

Response samples

Content type
application/json
{
  • "requisitionGroup": {
    }
}

職種グループの一覧を取得する

職種グループの一覧を取得することができます。

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ read
・ requisition:all
・ requisition:read

Responses

Response samples

Content type
application/json
{
  • "requisitionGroups": [
    ]
}

ユーザー一覧を取得する

ユーザー一覧を取得することができます。
下記の条件を指定することで絞り込むことが可能です。

このAPIを利用するには、APIキーを発行する際に、以下のいずれかのスコープを選択してください。
・ all
・ read
・ user:all
・ user:read

query Parameters
status
string
Enum: "active" "deactivated"

ユーザーの状態を指定して検索できます

値意味
active有効なユーザー
deactivated無効化されたユーザー
指定しない場合は全ての状態のユーザーを含みます

page
string

ページ番号を指定できる
1ページあたり100件のユーザーを取得する
指定しない場合は1ページ目を取得する

role
string
Enum: "admin" "recruiter" "assistant" "guest"

ユーザーの種類を指定して検索できます

値意味
admin管理者
recruiterリクルーター
assistantアシスタント
guestゲスト
指定しない場合は全ての種類のユーザーを含みます

direction
string
Default: "desc"
Enum: "asc" "desc"

作成日時でソートする際の順序を指定できます

値意味
asc昇順
desc降順
指定しない場合は降順でソートされます

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "hasNextPage": true
}