メインコンテンツにスキップ

APIの利用

APIを利用してTalentioの候補者情報を取得する方法を記載します。

この機能を利用できるプラン・権限


Enterprise

Business

Basic

Free

✖️

✖️

管理者権限

マネージャー権限

メンバー権限

✖️

✖️

この機能でできること


任意のフォーマットに整形して候補者情報を管理したり、分析したりすることができます。

APIについて


Talentioは人事や組織に関する様々なデータと簡単に連携できるよう、開発者向けAPIを公開しています。

開発者向けAPIの公開ページは以下からも確認ができます。

アクセストークンの設定


各種設定 > 基本設定 > 「API設定」画面を開きます。
ここでアクセストークンを発行することができます。

手順

説明

01

  • 左メニュー各種設定 > 基本設定 > API設定でトークンを発行します

02

以下用途に合わせて設定の上「発行する」ボタンを押下します。

  • トークンの名前 (管理用)

  • ワークスペースの範囲

    • すべてを対象にする

    • 特定のワークスペースを指定する

  • アクセス許可の範囲

    • ①すべてのAPIを許可する

    • ②許可するAPIおよび取得できる候補者項目を指定する

03

  • ①「すべてのAPIを許可する」で発行: トークンが表示されるのでコピーしてご利用下さい

  • ②「許可するAPIおよび取得できる候補者項目を指定する」で発行: 利用可能なAPIと取得可能な候補者項目が表示されるので必要な項目にチェックの上ご利用下さい

❗️ご注意ください

  • 個人情報およびセキュリティの観点から、APIトークンで取得できる求人や候補者の情報は、トークン発行者が所属しているワークスペースの範囲に限定されます。ワークスペース管理については、こちらをご確認ください。

  • トークンの発行ウィンドウを閉じた後は、トークンの確認ができません。発行されたトークンは忘れずにメモしておいてください。

💡ヒント

  • 「許可するAPIおよび取得できる候補者項目を指定する」ことで、トークン毎で利用を制限することができるため、用途別にご利用いただけます。

アクセス制限


TalentioではAPIアクセスを1時間に5,000リクエストまでに制限しています。
APIのレスポンスヘッダーには以下のアクセス情報が付加されます。

X-REMAINING: 4999 # 期間内にリクエストできる残りの回数
X-RESET: 1153    # 残り回数がリセットするまでの秒数

認証


リクエストヘッダーに以下のようにアクセストークンを付加してください。

curl -H 'Authorization: Bearer ACCESS_TOKEN' https://talentio.com/api/v1


レスポンスステータス


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

ステータスコード

説明

200

正常なレスポンス

400

パラメーターに不備があった

401

認証に失敗した

429

アクセス回数が制限を超えた

500

サーバー側で予期しないエラーが発生した

候補者


候補者一覧の取得

パラメータ

説明

デフォルト値

​page

取得するページ

1ページ内に含まれる候補者数は100です

1

status

候補者のステータスで絞りこみます

ongoing            # 選考中
reject             # 辞退
fail              # 不合格
pass              # 採用
poolActive      # コンタクト中
poolInactive  # 非コンタクト中

設定なし

sort

登録日もしくは応募日でソートができます

registeredAt     # 登録日昇順
-registeredAt   # 登録日降順
appliedAt           # 応募日昇順
-appliedAt         # 応募日降順

registeredAt

appliedAt

## jsonレスポンス
[{
  "id": 0,
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "description": "string",
  "requisition": {
    "id": 0,
    "name": "string",
    "active": true
  },
  "registeredAt": "2016-08-04T13:59:13+09:00",
  "appliedAt": "2016-08-03T13:59:13+09:00",
  "joinedAt": "2016-10-01T0:00:00+09:00",
  "stages": [{
    "id": 0,
    "type": "resume",
    "step": 1,
    "status": "ongoing"
  }],
  "status": "ongoing",
  "channelType": "agentCompany",
  "agentCompany": {
    "id": 0,
    "name": "string"
  },
  "priority": 0,
  "tags": [{
    "id": 0,
    "name": "string"
  }],
  "customFields": [
    {
      "name": "multi line",
      "value": "string\nstring\nstring"
    },
    {
      "name": "single line",
      "value": "string"
    },
    {
      "name": "number",
      "value": 256
    },
    {
      "name": "date",
      "value": "2016-08-17T00:00:00+09:00"
    }
  ]
}]

条件にマッチした候補者の総数はレスポンスのHTTPヘッダーに以下のように表示されます。

X-TOTAL: 100


候補者の追加

  • メソッド:POST

{
"lastName": "山田",
"firstName": "太郎",
"requisitionId": 1,
"status": "pass",
"lastNameKana": "やまだ",
"firstNameKana": "たろう",
"email": "test@example.com",
"priority": 1,
"gender": "male",
"birthday": "2022-01-01",
"address": "東京都",
"phone": "090-xxx-xxx",
"description": "サンプル補足",
"tagNames": [
"タグ1",
"タグ2"
],
"channel": {
"type": "site",
"agentEmail": "string",
"employeeEmail": "string",
"customChannelName": "string",
"customChannelNameOptional": "string"
},
"experiences": [
{
"company": "string",
"position": "string",
"startAt": "string",
"endAt": "string",
"description": "string",
"active": true
}
],
"educations": [
{
"school": "string",
"faculty": "string",
"startAt": "string",
"endAt": "string",
"description": "string",
"active": true
}
],
"customFields": [
{
"name": "string",
"value": null
}
],
"responsibleEmployees": [
" talentio@example.com"
],
"appliedAt": "2022-04-10T13:00:00+09:00",
"joinedAt": "2022-01-01"
}


候補者詳細の取得

## jsonレスポンス
{
  "id": 0,
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "requisition": {
    "id": 0,
    "name": "string",
    "active": true
  },
  "description": "string",
  "registeredAt": "2016-08-04T13:59:13+09:00",
  "appliedAt": "2016-08-03T13:59:13+09:00",
  "joinedAt": "2016-10-01T0:00:00+09:00",
  "stages": [{
    "id": 65891,
    "type": "contact",
    "step": 1,
    "scheduledAt": "2016-08-17T00:00:00+09:00",
    "status": "ongoing",
    "description": "string",
    "evaluations": [{
      "id": 0,
      "finished": false,
      "items": [{
        "name": "string",
        "type": "none"
      }],
      "employee": {
        "id": 1565,
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "active": true
      }
    }]
  }],
  "status": "poolActive",
  "channelType": "employee",
  "referrerEmployee": {
    "id": 0,
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "active": true
  },
  "priority": 0,
  "tags": [
    "id": 0,
    "name": "string"
  ]
}


候補者情報の更新

{
"lastName": "山田",
"firstName": "太郎",
"requisitionId": 1,
"lastNameKana": "やまだ",
"firstNameKana": "たろう",
"lastNameEn": "Yamada",
"firstNameEn": "Taro",
"email": "test@example.com",
"priority": 1,
"gender": "male",
"birthday": "2022-01-01",
"address": "東京都",
"phone": "090-xxx-xxx",
"description": "サンプル補足",
"tagNames": [
"タグ1",
"タグ2"
],
"channel": {
"type": "site",
"agentEmail": "string",
"employeeEmail": "string",
"customChannelName": "string",
"customChannelNameOptional": "string"
},
"experiences": [
{
"company": "string",
"position": "string",
"startAt": "string",
"endAt": "string",
"description": "string",
"active": true
}
],
"educations": [
{
"school": "string",
"faculty": "string",
"startAt": "string",
"endAt": "string",
"description": "string",
"active": true
}
],
"languages": [
{
"name": "string",
"level": 0
}
],
"licenses": [
{
"name": "string",
"acquiredAt": "string"
}
],
"medias": [
{
"type": "Facebook",
"account": "string"
}
],
"sites": [
{
"url": "string"
}
],
"customFields": [
{
"name": "string",
"value": null
}
],
"responsibleEmployees": [
" talentio@example.com"
],
"appliedAt": "2022-04-10T13:00:00+09:00",
"joinedAt": "2022-01-01"
}


削除済み候補者一覧の取得

[
{
"id": 0,
"deletedAt": "2019-08-24T14:15:22Z"
}
]


候補者のタグ設定

{
"tags": [
{
"candidateId": 1,
"tagNames": [
"タグA",
"タグB"
]
},
{
"candidateId": 2,
"tagNames": [
"タグC"
]
}
]
}


選考の追加


指定候補者の選考一覧を取得

指定した候補者の選考の一覧を取得します。

  • エンドポイント : (APIドキュメントの該当URL)

  • メソッド : GET

{
"id": 0,
"type": "string",
"step": 0,
"scheduledAt": "2019-08-24T14:15:22Z",
"scheduledAtEnd": "2019-08-24T14:15:22Z",
"description": "string",
"resultComment": "string",
"createdAt": "2019-08-24T14:15:22Z",
"fixedAt": "2019-08-24T14:15:22Z",
"status": "ongoing",
"evaluations": [],
"canNotifyResultCommentToAgent": true
}

※canNotifyResultCommentToAgentは、判定コメントをエージェントへ通知できるかどうかを表します。

指定候補者に任意の選考を追加

指定した候補者に対して任意の種別の選考を追加します。

パラメータ

説明

デフォルト値

​evaluations

評価者を以下のフォーマットで設定します

 [                           
{"employee" : "aaa@bbb.ccc"}, {"employee" : "ddd@eee.fff"} ]

必須

type

選考種別を以下の文字列で設定します

contact,resume,interview,reference,final

必須

scheduledAt

・選考日(共通の日程)をISO8601形式で設定します

例: '2005-08-15T15:52:01+0000'

※評価者ごとのscheduledAtと同時には指定できません

null

description

補足を文字列として設定します

空文字 

成功時のレスポンスには、作成された選考のID(data.id)が含まれます。

$ curl -i -H 'Authorization: Bearer [TOKEN]' -H 'Content-Type: application/json' https://talentio.com/api/v1/candidates/[candidateId]/stages -d '...'
HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Type: application/json
Date: Mon, 22 May 2017 14:58:04 GMT
Server: Apache/2.4.18 (Ubuntu)
Vary: Authorization
X-REMAINING: 994
X-RESET: 2745
Content-Length: 31
Connection: keep-alive

{"success":1,"data":{"id":123}}

評価者ごとに日程を指定する場合

evaluations内の各評価者にscheduledAtとdurationを設定することで、同じ選考でも評価者ごとに異なる日程を指定できます。

  • scheduledAt : 選考日をタイムゾーンを含むISO8601形式で設定します

  • duration : 選考の所要時間を分単位(15分単位の整数)で設定します。評価者のscheduledAtが設定されていてdurationがない場合は60分になります

{
"type": "interview",
"description": "一次面接",
"evaluations": [
{
"employee": "talentio1@example.com",
"formTemplateId": 1,
"scheduledAt": "2026-08-03T10:00:00+09:00",
"duration": 60
},
{
"employee": "talentio2@example.com",
"scheduledAt": "2026-08-04T14:00:00+09:00",
"duration": 30
}
]
}

❗️ご注意ください

評価者毎に日程を指定する場合、選考設定の個別指定のオプションが有効化されている必要があります。

利用される場合は、設定を有効化の上ご利用下さい。

・各種設定 > 基本設定 > 機能利用・権限設定 > 「選考日程の個別指定」を有効化

日程の指定方法と扱い

scheduledAt

評価者ごとのscheduledAt

扱い

なし

すべてなし

日程未設定で選考を追加

あり

すべてなし

共通の日程で選考を追加

なし

1件以上あり

評価者ごとの日程で選考を追加

あり

1件以上あり

エラー(HTTP 400)

※評価者ごとの日程を指定する場合でも、一部の評価者は日程未設定のままにできます。

指定候補者の指定選考を取得

指定した候補者の選考の詳細を取得します。取得できる情報は選考一覧と同一です。

  • エンドポイント : (APIドキュメントの該当URL)

  • メソッド : GET

指定候補者の指定選考を判定

指定した候補者の選考に対して判定を行います。

  • エンドポイント : (APIドキュメントの該当URL)

  • メソッド : POST

パラメータ

説明

デフォルト値

​result

判定結果を文字列で設定します

必須

comment

判定コメントを文字列として設定します

空文字

notifyResultCommentToAgent

判定コメントをエージェントへ通知するかを true / false で設定します

false

{
"result": "pass",
"comment": "経歴、スキルともに要件を満たしているため",
"notifyResultCommentToAgent": true
}

添付ファイル


指定候補者の添付ファイル一覧を取得

[
{
"id": 1,
"name": "resume.pdf"
}
]


指定候補者への添付ファイルを追加

{
"success": 1,
"data": [
{
"id": 1,
"name": "resume.pdf"
}
]
}


指定候補者の添付ファイルを削除

{
"success": 1
}

コメント


指定候補者へのコメント一覧を取得

## jsonレスポンス
[
  {
    "content": "string",
    "employeeCreatedBy": {
      "id": 0,
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "active": true
    },
    "createdAt": "2017-05-19T19:51:41+09:00",
    "updatedAt": "2017-05-19T19:51:41+09:00"
  },
  ...
]

contentに含まれるメンションは以下のようなフォーマットで出力されます

"1st line\n${xxx@yyy.zzz}\n3rd line"


指定候補者へのコメントを追加

パラメーター

説明

デフォルト値

content

評価者を以下のフォーマットで設定します

コメント取得のフォーマットと同じです

"1st line\n${xxx@yyy.zzz} \n3rd line"

必須

$ curl -i -H 'Authorization: Bearer [TOKEN]' -H 'Content-Type: application/json' https://talentio.com/api/v1/candidates/00000/comments -X POST -d '{"content":"hoge${xxx@yyy.zzz}"}'
HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Type: application/json
Date: Mon, 22 May 2017 14:50:28 GMT
Server: Apache/2.4.18 (Ubuntu)
Vary: Authorization
X-REMAINING: 996
X-RESET: 3201
Content-Length: 13
Connection: keep-alive{"success":1}

求人


求人一覧の取得

[
{
"id": 0,
"name": "string",
"jobTitle": {
"id": 0,
"name": "string"
},
"active": true,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]


求人の追加

{
"name": "サンプル求人名",
"jobTitleId": 1,
"status": "active",
"language": "ja",
"recruiterIds": [
1,
2
],
"recruiterGroupIds": [
1,
2
],
"workspaceIds": [
1,
2
],
"details": {
"defaultFields": {
"workDetail": {
"name": "職務内容",
"value": "職務内容の値"
},
"requiredQualifications": {
"name": "応募資格(必須)",
"value": "応募資格(必須)の値"
},
"preferredQualifications": {
"name": "応募資格(歓迎)",
"value": "応募資格(歓迎)の値"
},
"idealCandidateProfile": {
"name": "求める人物像",
"value": "求める人物像の値"
},
"salary": {
"name": "賃金",
"value": "賃金の値"
},
"workPlaces": {
"name": "勤務地",
"values": [
"勤務地1",
"勤務地2"
]
}
},
"additionalFields": [
{
"name": "任意項目名1",
"value": "任意項目の値1"
},
{
"name": "任意項目名2",
"value": "任意項目の値2"
}
]
}
}


求人詳細の取得

{
"id": 0,
"name": "string",
"jobTitle": {
"id": 0,
"name": "string"
},
"active": true,
"recruiters": [
{
"id": 0,
"name": "string"
}
],
"recruiterGroups": [
{
"id": 1,
"name": "サンプル採用担当グループ"
}
],
"jobDescriptionDetails": [
{
"name": "勤務時間",
"value": "フレックスタイム制"
}
],
"details": [
[
{
"name": "業務内容",
"value": "ポジションやそのポジションの魅力、具体的な業務内容などを記載してください"
},
{
"name": "勤務地",
"value": [
"東京都港区六本木6-3-1",
"日本全国転勤の可能性あり"
]
}
]
],
"companyDetails": [
{
"name": "設立",
"value": "2013年8月"
}
],
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

職種


職種一覧の取得

[
{
"id": 1,
"name": "サンプル職種名",
"publicName": "サンプル職種名(公開用)",
"requisitions": [
{
"id": 1,
"name": "サンプル求人名"
}
],
"createdAt": "2022-01-01T00:00:00+09:00",
"updatedAt": "2022-01-01T00:00:00+09:00"
}
]

チャネル


チャネル一覧の取得

[
{
"id": 0,
"channelType": "agent",
"channelName": "string",
"custom": {
"name": "string",
"optional": "string"
},
"employee": {
"id": 0,
"lastName": 0,
"firstName": 0,
"email": "string",
"active": "active"
},
"agentCompany": {
"id": 0,
"name": "string"
},
"agent": {
"id": 0,
"name": "string",
"email": "string",
"active": true
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]

評価フォームテンプレート


評価フォームテンプレート一覧の取得

[
{
"id": 0,
"name": "string"
}
]

評価


指定候補者の指定選考への評価を追加

{
"employeeId": 1,
"finished": true,
"items": [
{
"name": "サンプル評価タイトル1",
"type": "5level",
"input": 3,
"comment": "コメント"
},
{
"name": "サンプル評価タイトル2",
"type": "none",
"comment": "コメント"
}
]
}

メンバー


メンバー一覧の取得

[
{
"id": 1,
"name": "サンプルメンバー名",
"email": "sample@example.com",
"role": "manager",
"managerAssessment": true,
"status": "active",
"responsibleRequisitions": [
{
"id": 1,
"name": "サンプル求人名"
}
],
"groups": [
{
"id": 1,
"name": "サンプルグループ"
}
],
"lastAccessedAt": "2026-08-20T10:00:00+09:00",
"createdAt": "2022-01-01T00:00:00+09:00",
"updatedAt": "2022-01-01T00:00:00+09:00"
}
]

※lastAccessedAtは最終アクセス日時です。アクセス履歴がない場合はnullになります。

グループ


グループ一覧の取得

[
{
"id": 1,
"name": "サンプルグループ名",
"description": "サンプルグループの概要",
"employees": [
{
"id": 1,
"name": "サンプルメンバー名"
}
],
"createdAt": "2022-01-01T00:00:00+09:00",
"updatedAt": "2022-01-01T00:00:00+09:00"
}
]

ワークスペース


ワークスペース一覧の取得

[
{
"id": 1,
"name": "サンプルワークスペース名",
"description": "サンプルワークスペースの概要",
"status": "active",
"createdAt": "2022-01-01T00:00:00+09:00",
"updatedAt": "2022-01-01T00:00:00+09:00"
}
]

メール一覧の取得


送信メール一覧の取得

  • エンドポイント:ドキュメントのurl

  • メソッド:GET

レスポンスには、メールごとに候補者ID(candidateId)が含まれます。

{
"id": 0,
"candidateId": 0,
"subject": "string",
"body": "string",
"destinationType": "string",
"to": [],
"cc": [],
"bcc": [],
"from": [],
"replyTo": [],
"scheduledAt": "2019-08-24T14:15:22Z",
"sendAt": "2019-08-24T14:15:22Z"
}

受信メール一覧の取得

  • エンドポイント:ドキュメントのurl

  • メソッド:GET

レスポンスには、メールごとに候補者ID(candidateId)が含まれます。

{
"id": 0,
"candidateId": 0,
"subject": "string",
"body": "string",
"senderType": "string",
"to": [],
"cc": [],
"replyTo": [],
"from": [],
"receivedAt": "2019-08-24T14:15:22Z"
}

指定候補者への送信メール一覧を取得

  • エンドポイント:ドキュメントのurl

  • メソッド:GET

指定した候補者へ送信したメールの一覧を取得します。

{
"id": 0,
"subject": "string",
"body": "string",
"destinationType": "string",
"to": [],
"cc": [],
"bcc": [],
"from": [],
"replyTo": [],
"scheduledAt": "2019-08-24T14:15:22Z",
"sendAt": "2019-08-24T14:15:22Z"
}

指定候補者からの受信メール一覧を取得

  • エンドポイント:ドキュメントのurl

  • メソッド:GET

指定した候補者へ送信したメールの一覧を取得します。

{
"id": 0,
"subject": "string",
"body": "string",
"senderType": "string",
"to": [],
"cc": [],
"replyTo": [],
"from": [],
"receivedAt": "2019-08-24T14:15:22Z"
}

タグ一覧の取得


企業に登録されているタグの一覧を取得します。

  • エンドポイント : (APIドキュメントの該当URL)

  • メソッド : GET

パラメータ

説明

デフォルト値

page

取得するページ番号を設定します<br>1ページ100件、総件数はレスポンスヘッダのX-Totalで返されます

1

[
{
"id": 1,
"name": "リファラル",
"color": "#ff0000",
"status": "active",
"lockType": 1,
"createdAt": "2022-01-01T00:00:00+09:00",
"updatedAt": "2022-01-01T00:00:00+09:00"
}
]

❗️ご注意ください

  • 削除済みのタグは取得されません。有効・無効のタグはいずれも取得され、status(active: 有効 / inactive: 無効)で判別できます

  • 閲覧制限が設定されたタグも取得されます。制限の種類はlockType(1: ロックなし / 2: ロック / 3: マネージャーロック)で判別できます

  • 並び順はタグの作成順(id昇順)です。ATS画面上の表示順とは異なります

こちらの回答で解決しましたか?