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
}
エラーの一覧は下記の通りです。
codetypeHTTP ステータスコード原因
1bad_request400リクエストパラメータの内容が不正
2unauthorized_token401指定したアクセストークンが無効
3forbidden403リソースへのアクセスが禁止されている
4not_found404指定したリソースが存在しない
5internal_server_error500システム内部で予期せぬエラーが発生した
6too_many_requests429リクエスト制限の上限を超えた
7plan_limit_exceeded403上限人数に達しているため従業員の追加は出来ません
8non_deletable_resource400削除できないリソースです
9service_maintenance503メンテナンスを行っています

区分値の論理名

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