人事労務API 概要

freee人事労務 APIでできること

APIを利用するための認証(Oauth2.0)についてはAPIドキュメントおよびアクセストークンを取得するを参照してください。


ログインユーザーの情報を取得する

/users/me

ログインユーザーの情報を取得することができます。ユーザーが複数の事業所に所属している場合は各事業所毎に情報が出力されます。
ほとんどの人事労務APIで必要なcompany_id、およびemployee_idはこのAPIを利用して取得してください。

freee人事労務のWeb版をご利用いただく際には、契約プランにより権限グループは最大で3つありますが、API利用時は2つとなります。/users/meをご利用いただくことで、ログインユーザがどちらの権限をもってAPIからデータ取得できるのかがわかるようになっています。

  • Web:
    • 管理者
    • 従業員
    • 事務担当者(エンタープライズプランのみ)
  • API:
    • 管理者:company_admin
      • 例:他の従業員のデータに対してアクセスできる
    • 従業員(一般ユーザ):self_only
      • 例:自身に関する情報の閲覧や操作のみできる

従業員一覧を取得する

指定した事業所の従業員一覧を取得することができます。
employee_idを取得して勤怠入力に利用する他、入退社日やログインメールアドレスから、他クラウドサービスのアカウント管理などを行うことができます。
このAPIを用いて従業員情報の一元管理やアカウント削除漏れによるセキュリティリスク回避などを行うことが可能です。

2種類の従業員一覧APIがあります。目的にあわせて利用をしてください。

/companies/{company_id}/employees
  • 指定した事業所に所属する従業員をリストで返します
  • 指定した事業所に登録されている全ての従業員を取得することができます(削除済みの従業員を除く)
  • 詳細な従業員情報は取得できないため、追加情報が必要な場合は/api/v1/employees/{id}を合わせて利用する必要があります
/employees
  • 指定した事業所、指定した月に所属する従業員をリストで返します
  • year, monthの指定が必要です
    • 指定した月に存在する従業員のみ取得します
    • 指定月以前に退職済みの従業員や指定月時点で入社日を迎えていない従業員は取得結果に含まれません

日次勤怠を作成 / 更新 / 取得 / 削除する

/employees/{emp_id}/work_records/{date}

日付を指定して勤怠の作成 / 更新 / 取得 / 削除を行うことができます。
※作成 / 更新 はタイムレコーダー(打刻)機能とは異なり、勤怠データを直接入力した場合と同じ扱いとなります。

有給や欠勤についても設定ができます。詳細はAPIリファレンスのサンプルを参照してください。


月次勤怠を取得する

/employees/{emp_id}/work_record_summaries/{year}/{month}

指定した従業員、月次の勤怠情報情報を取得することができます。
またオプションを指定することで、月次勤怠のサマリとあわせて明細となる日次勤怠データを1ヶ月分まとめて取得することもできます。
このAPIを用いて、各従業員の月次勤怠情報を取得し、他社のシステムと連携したり、自社の独自ルールに合わせた勤怠管理ツールなどを開発することができます。


タイムレコーダー(打刻)情報を登録 / 取得 する

/employees/{emp_id}/time_clocks

指定した従業員のタイムレコーダー(打刻)情報を 登録 / 取得する ことができます。
登録の場合は、webの画面やアプリと同じく出勤 / 退勤 / 休憩開始 / 休憩終了 の登録ができます。
このAPIを用いて、自社のツール・ICカードや生体認証に対応した打刻機からAPIを呼び出すことで出退勤の管理を自動化することができます。

※タイムレコーダー(打刻)機能は、ベーシックプラン以上で有効です。
詳細はfreee人事労務のプラン・料金についてのヘルプをご覧ください


以下も併せて参照してください

  • freeeの基本的な使い方
    • 会計freeeを中心に、基本的な使い方や活用方法を学べるコンテンツのリンク集です。freeeについて知りたい方は、こちらをご覧ください。
  • freee APIスタートガイド
    • 最初のAPIコールに必要な環境準備とセットアップ、ブラウザでのAPIコールの方法などについて触れています。
  • freee人事労務 APIリファレンス
    • freee人事労務 APIの仕様を確認できます。アクセストークンを取得するとブラウザからのAPIコールもできるようになっています。