「この人の所属はどこか」「この部署の正社員は何人か」を確認するたびに SmartHR を開き、従業員リストを絞り込む作業が続きます。入社する人が決まれば、従業員の登録と招待のメールの送信も人事の手作業です。この記事は SmartHR を使っている人事・総務の担当者に向けて、SmartHR の公式 API を通して、AI チャットから従業員を調べ、入社する人を登録して招待する手順を説明します。
あわせて、SmartHR の API そのものの仕組みと、チャットから届かない情報も整理します。従業員の情報は扱いに気を遣うので、何が読めて何が読めないかを先に決めておく必要があるからです。
結論
- SmartHR には公式の API(SmartHR API)があります。管理者が SmartHR の［共通設定］>［外部システム連携］でアクセストークンを発行し、それを使って呼びます。トークンごとに、参照・更新を許可するリソースと従業員項目を選べます
- Samurai App の SmartHR 連携は、この公式 API を使います。チャットから会社の従業員を検索し、1 人の部署・雇用形態・役職・入社日などを見て、部署・雇用形態・事業所の一覧を確認できます
- 従業員の登録・更新・招待と部署の作成は、Samurai App の管理者とマネージャーだけが行えます。既定では、実行する前に確認が出ます
- 給与・源泉徴収・マイナンバー・家族・口座・年金番号・在留カードの情報は、チャットからは読み書きできません
SmartHR の従業員データを、ほかの仕組みから使う 3 つの方法
| 連携先サービスの機能 | 自分で API を呼ぶ | AI チャットから呼ぶ | |
|---|---|---|---|
| 向いている使い方 | 給与計算などへ決まった項目を渡す | 社内ツールへの定期的な取り込み | その場の調べ物と、1 人ずつの登録・更新 |
| 必要なもの | 連携先の設定と、SmartHR のアクセストークン | 開発する人と、アクセストークン | 連携の設定と、アクセストークン |
| 頼み方 | 連携先の画面で決まった操作 | プログラムに書いた処理 | 言葉で頼む |
連携先サービスの機能 は、SmartHR のヘルプにも給与計算サービスなどとの連携設定の記事が並んでいます。渡す項目と向きは、連携先ごとに決まっています。
自分で API を呼ぶ 場合、呼び先は https://<サブドメイン>.smarthr.jp/api です。アクセストークンは BASIC 認証か Authorization: Bearer のヘッダーで渡します。回数の上限はアクセストークンごとに 1 秒 10 回・1 時間 5,000 回、サブドメインごとに 1 分 50,000 回です。試すためのサンドボックス環境もあり、申し込みのフォームから使えます。SmartHR をまだ使っていない会社でも申し込めますが、従業員のデータは予告なく消されることがあります。
AI チャットから呼ぶ のが、この記事で説明する方法です。中身は 2 つ目と同じ公式 API で、呼び方を言葉に変えたものです。
なお、アクセストークンの発行方法のヘルプ記事では、対象プランとして「労務管理」「人事・労務エッセンシャル」「¥0」「HRストラテジー」が挙がっています。自社の契約で使えるかは SmartHR の管理画面か担当窓口で確認してください。
Samurai App でできること・できないこと
設定画面の「チャットからできること」に並ぶ操作は、次の 2 つに分かれます。
見る(自分の SmartHR アカウントを確認した人なら誰でも)
- 自分がどの従業員として操作するかを確認する
- 従業員を検索する。氏名・社員番号・部署・雇用形態・在籍状況(在籍・休職・退職)で絞れます。1 回 100 人まで、続きはページを進めて読みます
- 従業員を 1 人開いて、部署・雇用形態・役職・入社日などを見る。読める項目は氏名とフリガナ、ビジネスネーム、社員番号、メールアドレス、入社日と退職日、在籍状況、部署、雇用形態、役職、等級、職種、事業所です
- 部署の一覧(上位の部署を含む正式な名前つき)、雇用形態の一覧、事業所の一覧を見る
登録・更新する(管理者とマネージャーだけ。既定では実行する前に確認が出ます)
- 従業員を登録する。必要なのは姓と名だけで、ほかの項目は分かる分だけ入れます
- 従業員の情報を更新する(異動・退職・社員番号の修正など)。変える項目だけを送り、ほかはそのまま残ります。部署は送った一覧で丸ごと置き換わります
- 従業員を SmartHR に招待する。招待のメールは、その従業員に登録されているメールアドレスへ届きます。もう一度頼むと送り直します
- 部署を作る。部署の名前に「/」は使えません
できないこと
- 給与・源泉徴収・マイナンバー・家族・口座・年金番号・在留カードの情報を読むことと書くこと
- 従業員の削除
- 手続き、届出書類、年末調整、給与明細の操作
- カスタム項目の読み書き、役職・等級・職種の書き換え
- 招待者を自分以外にすること。招待は必ず頼んだ本人の名前で送られ、本人の SmartHR のユーザーが SmartHR の管理者である必要があります
使い方 1: 部署と雇用形態で従業員を調べる
人事に届く「この人はどこの所属か」という問い合わせや、部署ごとの人数の確認は、チャットで頼むと表で返ります。
SmartHR で、開発部に在籍している契約社員を、氏名・役職・入社日の表にして
部署と雇用形態での絞り込みには、SmartHR の中の ID を使います。そのため AI は先に部署の一覧と雇用形態の一覧を読んでから従業員を検索します。
1 人について知りたいときは、氏名か社員番号を伝えます。
社員番号 1024 の人の、部署・役職・等級・入社日を教えて
使い方 2: 入社する人を登録して、招待のメールを送る
入社が決まった人の登録と招待は、管理者かマネージャーが頼みます。
4 月 1 日に入社する人を SmartHR に登録して。
姓は佐藤、名は花子、フリガナはサトウ ハナコ、雇用形態は正社員、部署は営業部、メールアドレスは hanako.sato@example.com。
登録できたら、SmartHR の招待を送って
AI は雇用形態と部署の一覧から当てはまるものを選び、登録の内容を承認カードに出します。内容を読んで許可すると登録され、続けて招待の承認カードが出ます。許可すれば、頼んだ人の名前で招待のメールが送られる流れです。
用意するもの
- SmartHR の管理者(アクセストークンを発行する人)
- Samurai App の管理者かマネージャー(SmartHR と連携する人)
- 使う人それぞれの Samurai App のアカウント。メールアドレスが SmartHR に従業員として登録されているものと同じであること
手順
1. SmartHR でアクセストークンを発行する
SmartHR の管理者が次の順で発行します。
- ホームにあるアプリ一覧の［共通設定］>［外部システム連携］を押す
- ［アクセストークン］を押す
- ［+新規発行］を押し、［アクセストークン名］を入力して［登録］を押す
- ［リソースのアクセス許可］と［従業員項目のアクセス許可］で、参照と更新を許可する範囲を選ぶ
- 発行されたアクセストークンを取得する
チャットから登録や招待をしないなら、更新を許可せずに発行する方法もあります。アクセス制限ルールで IP アドレスを絞ったトークンは使えません。Samurai App からの送信元の IP アドレスは固定されないためです。
2. 管理者が Samurai App で SmartHR と連携する
「コネクタ」の画面(/settings/connections)を開き、「API 連携」タブの「API 連携を追加」を押します。一覧から SmartHR を選ぶと、設定の欄が開きます。
- 「環境」: 「本番」か「サンドボックス」
- 「サブドメイン」: SmartHR を開いたときの URL の
https://のすぐ後ろ、最初の「.」までの部分 - 「アクセストークン」: 手順 1 で取得したトークン
入力したら「SmartHR と連携する」を押します。「連携済み」と出れば完了です。トークンに期限はありません。
3. 使う人がそれぞれ本人確認をする
使う人は同じ画面の SmartHR の設定で「自分の SmartHR アカウントを確認する」を 1 回押します。Samurai App のメールアドレスと同じ SmartHR のユーザーに結びつき、チャットからはその従業員として操作します。SmartHR に従業員として登録されていない人は確認できず、チャットから SmartHR を使えません。
4. チャットで頼む
チャットで、何を調べるか、誰を登録するかを具体的に頼みます。登録・更新・招待は承認カードを読んでから許可します。
注意点
本人確認をした人は、会社の従業員全員を検索できます。 部署・役職・入社日・メールアドレスなどが、管理者でないメンバーにも表示されます。社内の名簿として誰に見せてよい範囲かを、連携する前に決めてください。
更新では、部署の一覧が丸ごと置き換わります。 兼務している人の部署を 1 つ追加するつもりで 1 つだけ送ると、元の部署が外れます。承認カードの部署の欄に、残したい部署がすべて入っているかを確認してください。
SmartHR のユーザーが 3,000 人を超える会社では、本人確認ができない人が出ることがあります。 「自分の SmartHR アカウントを確認する」を押しても、結びつかないことがあります。
連携を解除すると、全員の本人確認も外れます。 再接続したあとは、各自がもう一度確認します。別のサブドメインで連携し直したときも同じです。アクセストークン自体は Samurai App の解除では消えないので、使わなくなったら SmartHR の管理画面で削除します。
サンドボックスで試すときは、データが消えることを前提にします。 サンドボックス環境の従業員のデータは、SmartHR が予告なく片づけることがあります。
よくある質問
給与やマイナンバーを AI に読ませずに済みますか
済みます。Samurai App の SmartHR 連携は、給与・源泉徴収・マイナンバー・家族・口座・年金番号・在留カードの情報を SmartHR に要求しません。頼まれても届かない作りです。
退職した人の情報も更新できますか
できます。管理者かマネージャーが「この人の在籍状況を退職にして、退職日を 3 月 31 日にして」のように頼みます。退職に合わせて社内のほかのアカウントを停止する手順は退職者のアカウント削除とパスワード変更にまとめました。
メンバーでも従業員を登録できますか
できません。登録・更新・招待と部署の作成は、Samurai App の管理者とマネージャーだけが呼べます。メンバーが頼むと、承認カードを出す前に断ります。
招待のメールが届かないと言われました
招待のメールは、その従業員に登録されているメールアドレスへ送られます。先に「この人のメールアドレスを見せて」と頼んで確認し、違っていれば更新してから「もう一度招待を送って」と頼みます。
連携のときに「SmartHR がアクセストークンを受け付けませんでした」と出ます
環境・サブドメイン・アクセストークンを確認します。サブドメインは URL の一部だけを入れ、https:// や .smarthr.jp は含めません。トークンのアクセス制限ルールで IP アドレスを絞っている場合も繋がりません。
出典
- アクセストークンの発行方法(SmartHR ヘルプセンター)
- API概要(SmartHR Developers)
- Sandbox概要(SmartHR Developers)
- 外部サービスとの連携(Samurai App の使い方)
- API 連携の各サービスの繋ぎ方(Samurai App の使い方)
2026 年 11 月 9 日時点で、SmartHR のヘルプセンターと開発者向けの文書を確認したものです。