CastingONE API Specifications (1.0.0)

API に぀いお

゚ンドポむント

API の゚ンドポむントは環境ごずに以䞋の URL になりたす。

  • 本番環境: https://tn.lb.core.lite.casting-one.jp/api/v1
  • ステヌゞング環境: https://tn-stg.lb.core.lite.casting-one.jp/api/v1

事前怜蚌ではステヌゞング環境をご利甚ください。正匏リリヌス時は本番環境の゚ンドポむントぞ切り替えおください。

認蚌

API の利甚にはアクセスキヌずアクセストヌクンが必芁です。 アクセスキヌずアクセストヌクンは管理サむトから発行できたす。(事前に API 連携の利甚申請が必芁です) アクセスキヌずアクセストヌクンは、リク゚ストヘッダに以䞋のように含めおください。

curl -X GET \
-H 'x-api-key: API_KEY' \
-H 'x-api-token: API_TOKEN' \
https://tn.lb.core.lite.casting-one.jp/

ステヌゞング環境を利甚する堎合は、䞊蚘 URL のホスト名を tn-stg.lb.core.lite.casting-one.jp に差し替えおください。

ペヌゞネヌション

リストを返す API では䞀床に返せる芁玠の数が限定されおおり、より倚くの芁玠が必芁ずなる堎合はペヌゞを指定する必芁がありたす。リストの API には、1 から始たるペヌゞ番号を衚す page パラメヌタず、1 ペヌゞあたりに含たれる芁玠数を衚す per_page パラメヌタを指定するこずができたす。page の初期倀は 1 に蚭定されおいたす。たた、per_page の初期倀は 50、per_page の最倧倀は 100 に蚭定されおいたす。

たた、芁玠の総件数はレスポンスの total_count で確認できたす。䟋えば候補者の総件数が 1000 件の堎合は以䞋のようなレスポンスになりたす。

{
  "total_count": 1000,
  "candidates": [...]
}

゜ヌト

リストを返す API では、䞊び順を特定のキヌで指定できる sort_by パラメヌタず、昇順降順を指定できる sort_desc パラメヌタが甚意されおいるこずがありたす。䟋えば候補者を「䜜成日時」の「降順」で䞊べる堎合は以䞋のようになりたす。

https://tn.lb.core.lite.casting-one.jp/api/v1/candidates?sort_by=created_at&sort_desc=1

区分倀に぀いお

候補者や求人の各リ゜ヌスで利甚する区分倀のリストです。

性別

倀内容
1男性
2女性

血液型

倀内容
0䞍明
1A
2B
3O
4AB

曜日

倀内容
1月
2火
3æ°Ž
4朚
5金
6土
7日
100祝

芖力

倀内容
00.1未満
10.1
20.2
30.3
40.4
50.5
60.6
70.7
80.8
90.9
101.0
121.2
151.5
202.0以䞊

候補者ステヌタス皮別

倀内容
0組み蟌み
1远加

組み蟌み候補者ステヌタス

倀内容
0未応募
1応募
2スタッフ登録
3芋送り
4蟞退
5登録解陀
6統合

求職意欲

倀内容
0積極的に怜蚎
1怜蚎䞭
2案件次第
3求職意欲なし

雇甚圢態

倀内容
0正瀟員
1掟遣瀟員
2契玄瀟員
3アルバむト・パヌト
4短時間正瀟員
5業務委蚗
6家内劎働者
7自営型テレワヌカヌ
8その他

テナントマスタに぀いお

各リ゜ヌスに含たれるテナントマスタ倀の察応に぀いおはマスタ取埗 API を利甚しおご確認ください。

倖郚連携甚ID

候補者の倖郚連携甚IDは、連携先ごずに持ちたす。候補者APIでは provider_external_ids で連携先ごずの倖郚連携甚IDを読み曞きしたす。

"provider_external_ids": [
  { "provider_id": 1, "external_ids": ["A-001"] },
  { "provider_id": 2, "external_ids": ["B-001", "B-002"] }
]

連携先の確認方法

provider_id は、管理サむトの 蚭定 > カスタム > 倖郚連携甚ID の䞀芧の ID 列で確認できたす。この倀を、リク゚ストの provider_id ず、䞋蚘の連携先を指定する゚ンドポむントの {provider_id} に䜿甚しおください。

非掚奚のフィヌルドず゚ンドポむント

埓来の倖郚連携甚IDである、次の゚ンドポむントずフィヌルドは、最もIDの若い連携先の倖郚連携甚IDずしお動䜜したす。2027幎4月に廃止予定です。 移行手順に埓い、新しい゚ンドポむントに切り替えおください。

  • GET / PUT / DELETE /candidates/external/{external_id}
  • リク゚ストの external_id
  • レスポンスの external_ids

移行手順

  1. 候補者の特定に䜿う゚ンドポむントを /candidates/external/{external_id} から /candidates/providers/{provider_id}/external_ids/{external_id} に切り替えおください
  2. リク゚ストの external_id ずレスポンスの external_ids の代わりに、provider_external_ids を䜿甚しおください

フリヌ項目に぀いお

候補者APIのリク゚スト・レスポンスにあるfree_itemsのvalueは、入力圢匏によっおデヌタ型ず圢匏、登録可胜な倀が倉わりたす。

入力圢匏デヌタ型・圢匏登録可胜な倀
1:1行テキスト文字列500文字以内
2:耇数行テキスト文字列5000文字以内
3:数倀数倀0~9999999
4:単䞀遞択数倀フリヌ項目マスタのmasters.id
5:耇数遞択数倀の配列フリヌ項目マスタのmasters.id
6:幎月日文字列(yyyy/mm/dd圢匏)100幎前~100幎埌
7:幎月文字列(yyyy/mm圢匏)100幎前~100幎埌
8:時刻文字列(hh:mm圢匏)00:00~23:45。15分単䜍

ファむルの URL に぀いお

API のレスポンスに含たれるファむルの URL には有効期限がありたす。5 分以内にアクセスするようにしおください。

Webhook に぀いお

求職者が応募したり、候補者曎新フォヌムに回答するなどのむベント発生時に、蚭定した URL ぞ Webhook むベントオブゞェクトを含む HTTP POST リク゚ストを送信するこずが可胜です。

認蚌眲名怜蚌

Webhook のリク゚ストが届いたら、リク゚ストヘッダに含たれる眲名を怜蚌しおください。この怜蚌により「CastingONE サヌバから送信された Webhook リク゚ストである」、「通信途䞭で改ざんされおいない」こずを確認するこずができたす。

CastingONE サヌバでは、Webhook リク゚ストボディを入力デヌタ、シヌクレットトヌクンをハッシュ鍵ずしお HMAC-SHA256 で眲名を䜜成し、X-CastingONE-Signature ヘッダずしお付䞎したす。 Webhook リク゚ストず眲名は以䞋の手順で怜蚌できたす。

  1. 受信した Webhook リク゚ストボディの文字列を入力デヌタ、Webhook 蚭定䜜成時のシヌクレットトヌクンをハッシュ鍵ずしお、HMAC-SHA256で眲名を生成したす。
  2. 受蚺した眲名( X-CastingONE-Signature )ず、生成した眲名を比范したす。
  3. 眲名が䞀臎した堎合は、Webhook リク゚ストの凊理を行うこずができたす。

眲名が䞀臎しない堎合は、リク゚ストが CastingONE サヌバ以倖から送信された、通信途䞭で改ざんされた、あるいは怜蚌手順に誀りがある可胜性がありたす。

眲名怜蚌の䟋

Go:

func verifySignature(secretToken string, body []byte, signature string) bool {
    hash := hmac.New(sha256.New, []byte(secretToken))
    hash.Write(body)
    expected := hex.EncodeToString(hash.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signature))
}

Node.js:

const crypto = require("crypto");

function verifySignature(secretToken, body, signature) {
  const expected = crypto
    .createHmac("sha256", secretToken)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

再送

Webhook は次の条件で再送されたす。再送は䞀定期間詊行したのち打ち切られたす。

  1. 受信サヌバが䞀定時間内に応答を返さなかったずき
  2. 受信サヌバが 200 番台以倖のステヌタスコヌドを返したずき

重耇排陀

通信経路䞊の問題などにより、同じ Webhook むベントが重耇しお送信される可胜性がありたす。各 Webhook むベントオブゞェクトには䞀意な event_id が付䞎されるため、これを利甚しお重耇の怜出を行うこずができたす。

Servers
//tn.lb.core.lite.casting-one.jp/api/v1