IT管理の操作
freeeIT管理APIを使った SaaSアカウント・備品・メンバー管理ガイド。IT管理 API はオープンベータで、仕様は予告なく変更される可能性がある。
リソース
- メンバー:
/hub/it_management/members— 従業員（IT管理上の利用者） - SaaSアカウント:
/hub/it_management/application_accounts— 各 SaaS 上のアカウント。メンバーに紐付く - 備品:
/hub/it_management/assets— PC・周辺機器など物理資産。メンバーに利用者として割当 - 備品ステータス:
/hub/it_management/asset_statuses— 備品の状態ラベル（例: 使用中 / 保管中）。備品のasset_status_idから参照される - 備品種別:
/hub/it_management/asset_categories— 備品の種類ラベル（例: ノートPC）。備品のasset_category_idから参照される - 部署:
/hub/it_management/departments— 組織階層上の部署。メンバーのdepartment_idsから参照される
認証と事業所スコープ
- 認証は OAuth2（
read/writeスコープ）。freee 共通の認可フローを利用する - 操作対象の事業所を
company_idで指定する。指定値は現在の事業所（freee_get_current_company）と一致する必要があり、不一致だとエラーになる。切り替えはfreee_set_current_companyを使う company_idの位置はメソッドで異なる。GET（一覧・単体取得）/ DELETE はクエリパラメータ、POST / PATCH はリクエストボディ（いずれも必須）
ページネーション
一覧取得（GET）はすべてカーソルベース。offset / limit ではない点に注意。
- 1ページ目:
company_id（必須）のみで GET - 2ページ目以降: 直前のレスポンスの
next_page_tokenを querypage_tokenに渡す
freee_api_get {
"service": "it_management",
"path": "/hub/it_management/members",
"query": { "company_id": 123456, "page_token": "eyJ..." }
}page_size上限は 100。超過するとAHB-3003-0002- 並び順は
created_at DESC固定。updated_at/name等のソート指定には対応していない
キーワード検索の対象
keyword クエリは部分一致 OR 検索。対象はリソースごとに異なる。
- メンバー:
family_name/given_name/yomi/code/phone_number/ 部署名 /login_email/ カスタム属性 - SaaS アカウント:
account/external_id/data内 attribute 値 - 備品:
asset_number/serial_number/ 利用者名 / 各 attribute 値
ヒット範囲が広いため、絞り込みたい場合は別途フィルタ（status_id, application_id 等）と組み合わせる。
削除の挙動
API ごとに削除の意味が違うので注意。
- メンバー削除・SaaSアカウント削除: ソフトデリート
- 備品削除: ハードデリート（復元不可）。誤削除すると戻せないため、削除前にユーザー確認を行うこと
- 備品ステータス・備品種別: 該当マスタを参照している備品が1件でも残っていると削除できない（
system-managedな備品種別も削除不可）。移行が必要なら先に対象備品のasset_status_id/asset_category_idを別のマスタに付け替える - 部署: 子部署が存在する、またはメンバーの
department_idsに含まれている場合は削除できない
SaaSアカウント (application_accounts) の特殊仕様
Write 系はカスタムアプリ限定
POST / PATCH / DELETE /hub/it_management/application_accounts/* はカスタムアプリ（ユーザーが手動で追加した管理対象 SaaS）配下のアカウントのみ受け付ける。Slack / Microsoft 365 等の自動同期で取り込まれた標準アプリのアカウントは Write 系が拒否され、ITM-05-02-0003 が返る。
カスタムアプリかどうかを事前判定する API は提供されていないため、Write 試行時のエラーで判別する。
POST と PATCH で受け付けるフィールドの差
POST /application_accounts は attributes をリクエストボディに含められない（ゲートウェイで AHB-3003-0002 unsupported）。属性値の設定は、作成直後にレスポンスの id を使って PATCH /application_accounts/{id} を続けて呼ぶ二段階運用が必要。
attributes（カスタム属性）の操作
カスタムアプリは「アカウントID / 表示名 / 権限 / ライセンス / ステータス / …」などの動的属性を持つ。
- 属性スキーマは
GET /application_accounts/{id}レスポンスのapplication.attributesから取得できる。有効な title はこれを参照して把握する - 更新リクエストの
attributesキーは UUID（attribute.id）または title 名のどちらでもよい。同一アプリ内で title はユニーク制約があるため安全に逆引きされる
PATCH /hub/it_management/application_accounts/{id}
{
"company_id": 123456,
"attributes": { "表示名": "Yamada Taro", "権限": "Administrator" }
}- 部分更新では送信していない attribute は既存値が維持される。明示的に
nullを送れば NULL クリア可能 is_display: trueの属性は必須。既存値が無い状態で省略するとITM-05-02-0001 表示名を入力してください(422)。一度値をセットすれば、以降の部分更新で省略しても既存値が保持されるis_status: trueの属性に値をセットするとstatus.idが連動切替される- 未知の title キーは無音で無視される（エラーにならない）。タイポに気付けないため、送信前に
application.attributesの title セットに含まれていることを確認すること
ステータス・ロール
application_account_status_id/application_account_role_idを PATCH ボディで指定可能- 不正な UUID は
ITM-05-02-0001+invalid_fieldsで 422 application_account_role_id: nullで既存ロールをクリア
よくある操作の流れ
メンバー登録 → SaaS アカウント紐付け
- メンバーを作成（POST
/hub/it_management/members） - レスポンスの
idをapplication_accountのmember_id系フィールドに利用してアカウント作成（POST/hub/it_management/application_accounts、カスタムアプリのみ）
メンバーの department_ids は GET /hub/it_management/departments で参照可能。同様に、備品の asset_status_id は /asset_statuses、asset_category_id は /asset_categories で一覧を取得してから割り当てられる。position_id / employment_type_id には対応する一覧取得エンドポイントが提供されていないため、事前に値を持っている前提で扱う。不正な ID は ITM-05-03-0001 の 422 で返り、fields 配列で具体的なフィールド名が判別できる。
メンバーの primary email（PATCH /members/{id} の email）は API での更新に対応していない。
メンバーに紐づくアカウント・備品の棚卸し
特定メンバーの利用状況を横断的に確認したいとき（入退社時の棚卸し等）は、各一覧をメンバーで絞り込む。
- SaaSアカウント: GET
/hub/it_management/application_accountsをmember_id（アカウントホルダー）で絞り込み - 備品: GET
/hub/it_management/assetsをmember_id（利用者）で絞り込み - メンバー一覧自体は雇用形態（
employment_type_id）・入社日/退職日の範囲でも絞り込める。退職者の洗い出しは退職日の範囲指定が使える
employment_type_id のように対応するマスタ一覧 API がない参照 ID は、既存メンバーの一覧レスポンス（employment_type.id）から値を取得する。
備品の貸与状況を更新
- 備品一覧を取得し対象を特定（GET
/hub/it_management/assets） - PATCH
/hub/it_management/assets/{id}で更新する
備品 PATCH のリクエストボディに current_member_id を含めるとゲートウェイで AHB-3003-0002 unsupported で拒否される。API からメンバーへの貸与状況変更は不可で、UI 側での操作が必要。
部分更新
更新系（PATCH）は指定したフィールドのみが更新される。null クリアの挙動はフィールドごとに異なるため、必ず差分のみを送る。
エラーコードの読み方
code を見れば発生源と扱い方が分かる。ITM- 系と AHB-3003-0002 はいずれも fields を持つので、具体的なフィールドエラーはそこから取得する。
ITM-05-01-XXXXは備品 API、ITM-05-02-XXXXは SaaS アカウント API、ITM-05-03-XXXXはメンバー API 由来AHB-3003-0002は API ゲートウェイ層のスキーマ違反（必須項目欠落 / 型不一致 /unsupportedフィールド送信 /page_size上限超過 等）AHB-1002-9001はシステムエラー（5xx）。通常運用では発生しない
よくあるケース:
- 401/403: 認証エラー。
freee_auth_statusで確認。Remote MCP は再認証を促される。ローカルはfreee_clear_auth→freee_authenticate - 404 +
ITM-05-XX-0002: 指定 ID のリソースが存在しない、または既にソフトデリート済み - 422 +
ITM-05-XX-0001: 不正な参照 ID（status_id / role_id / position_id 等） - 400 +
ITM-05-XX-0001: 一意制約違反（asset_number,serial_number,external_id,code等のチーム内一意フィールド） - 400 +
ITM-05-02-0003: カスタムアプリでない SaaS アカウントへの Write
リファレンス
パス一覧・パラメータ・レスポンスの詳細は以下を参照:
references/it-management-members.md- メンバーreferences/it-management-application-account.md- SaaSアカウントreferences/it-management-assets.md- 備品references/it-management-asset-statuses.md- 備品ステータスreferences/it-management-asset-categories.md- 備品種別references/it-management-departments.md- 部署