API概要

SmartHR API の仕様について

エンドポイント

API のエンドポイントは以下の URL になります。

https://*.smarthr.jp/api

* には所属しているテナントのサブドメインが入ります。

リクエスト制限

SmartHR APIには、アクセストークンごとのリクエスト制限と、サブドメインごとのリクエスト制限があります。

アクセストークンごとのリクエスト制限

発行したアクセストークンごとに、1時間で5000回までリクエストできます。レスポンスには、リクエスト制限の情報を表す以下のヘッダーが含まれています。

ヘッダー名	説明
x-rate-limit-limit	期間内でリクエストできる最大回数
x-rate-limit-reset	制限がリセットされるまでの秒数
x-rate-limit-remaining	リクエストできる残り回数

サブドメインごとのリクエスト制限

サブドメインごとに、1分間で50000回までリクエストできます。レスポンスには、リクエスト制限の情報を表す以下のヘッダーが含まれています。

ヘッダー名	説明
x-intensive-rate-limit-limit	期間内でリクエストできる最大回数
x-intensive-rate-limit-reset	制限がリセットされるまでの秒数
x-intensive-rate-limit-remaining	リクエストできる残り回数

ページネーション

リストを返す API では一度に返せる要素の数が限定されていて、より多くの要素が必要となる場合はページを指定する必要があります。リストの API には、1から始まるページ番号を表す page パラメータと、1ページあたりに含まれる要素数を表す per_page パラメータを指定することができます。page の初期値は 1 に設定されています。また、per_page の初期値は 10、per_page の最大値は 100 に設定されています。ページを指定できる API のレスポンスには Link ヘッダが含まれます。Link ヘッダには、最初のページと最後のページへのリンクと、存在する場合には次のページと前のページへのリンクが含まれます。これらのリンクは、first, last, next, prev という rel 属性の値で識別されます。

Link: <https://*.smarthr.jp/api/v1/crews?page=1>; rel="first",
      <https://*.smarthr.jp/api/v1/crews?page=4>; rel="prev",
      <https://*.smarthr.jp/api/v1/crews?page=6>; rel="next",
      <https://*.smarthr.jp/api/v1/crews?page=14>; rel="last"

また、x-total-count ヘッダでリクエストに対する要素の総件数が確認できます。

x-total-count: 37

ソート

リストを返す API では、並び順のキーとなるプロパティを指定できる sort パラメータが用意されていることがあります。例えば、従業員を「在籍状況別」に並べる場合は以下のようなリクエストになります。

https://*.smarthr.jp/api/v1/crews?sort=emp_status

また、複数のソートを組み合わせられる場合もあります。先ほどの例に加えて「最近更新した順」で並べる場合は、以下のようにします。（プロパティの先頭にハイフンをつけると並びが降順になります）

https://*.smarthr.jp/api/v1/crews?sort=emp_status,-updated_at

認証

API の利用にはアクセストークンが必要です。アクセストークンはユーザの管理画面から発行できます。以下のいずれかの方法でリクエストに含めてください。

アクセストークンの発行は管理者のみ可能です。権限をお持ちでない場合は、組織の SmartHR 管理者へお問い合わせください。

BASIC 認証

curl -u ACCESS_TOKEN https://*.smarthr.jp/

リクエストヘッダ

curl -H 'Authorization: Bearer ACCESS_TOKEN' https://*.smarthr.jp/

エラーレスポンス

API リクエストでエラーが発生した場合、その原因を含むエラーレスポンスを返します。
code はエラーの原因毎に一意に振られたコード、type はエラーの型、message は原因の説明を示します。errors には送られたリソースのプロパティにエラーがあった場合の説明が入ります。

{
  code: 2,
  type: "unauthorized_token",
  message: "無効なアクセストークンです",
  errors: null
}

エラーの一覧は下記の通りです。

code	type	HTTP ステータスコード	原因
1	bad_request	400	リクエストパラメータの内容が不正
2	unauthorized_token	401	指定したアクセストークンが無効
3	forbidden	403	リソースへのアクセスが禁止されている
4	not_found	404	指定したリソースが存在しない
5	internal_server_error	500	システム内部で予期せぬエラーが発生した
6	too_many_requests	429	リクエスト制限の上限を超えた
7	plan_limit_exceeded	403	上限人数に達しているため従業員の追加は出来ません
8	non_deletable_resource	400	削除できないリソースです
9	service_maintenance	503	メンテナンスを行っています

区分値の論理名

各リソースに含まれる区分値の物理名と論理名の対応は「SmartHR API 区分値リスト」よりご確認ください。
国コードは ISO 3166-1 を利用しています。