SmartHR

SmartHR

This connector uses the SmartHR API v1 (https://<tenant>.smarthr.jp/api/v1) of SmartHR, the HR and labour management cloud used in Japan: employees (従業員, called crews in the API) with departments, job titles, employment types, grades, work locations and custom fields, their dependents and leaves, user accounts, invitations, and payroll runs with payslips. The sandbox (<tenant>.daruma.space) works the same way.

Personal data: SmartHR holds sensitive personal data (家族, addresses, birth dates, insurance and pension numbers, bank accounts, salary). Read only what the task needs: smarthr_list_crews returns a short profile by default, and fields limits smarthr_get_crew too. Do not copy personal data into other systems or messages unless the user asks for exactly that.

Setup (about 5 minutes, SmartHR admin)

1. Sign in to SmartHR as an administrator (管理者). Open 共通設定 (Common settings), 外部システム連携 (External integrations), アクセストークン (Access tokens), and click 新規発行 (Issue).
2. Name the token and choose its permissions: reading (参照) for the data the AI should see (従業員, 部署, 役職, 雇用形態, カスタム項目, 家族, ユーザー, 給与明細 as needed) and updating (更新) only for the write tools you keep on. Fewer permissions mean less personal data exposed.
3. Copy the token into SMARTHR_ACCESS_TOKEN; it is shown once, so keep it secret.
4. Enter the host of your SmartHR address in SMARTHR_HOST: example.smarthr.jp for https://example.smarthr.jp, or example.daruma.space for the sandbox (apply at https://developer.smarthr.jp/api/about_sandbox).
5. Install. The check runs smarthr_list_companies.

Workflow

• Company structure: smarthr_list_companies, smarthr_list_biz_establishments, smarthr_list_departments, smarthr_get_department, smarthr_list_job_titles (役職), smarthr_list_employment_types, smarthr_list_grades, smarthr_list_work_locations, smarthr_list_payment_periods.
• Custom fields: smarthr_list_crew_custom_field_templates (template ids for writes) and smarthr_list_crew_custom_field_template_groups.
• Find people: smarthr_list_crews by q, emp_code, emp_status, department, title, dates; smarthr_get_crew for one person. For changes since a date sort by -updated_at and stop at older rows (there is no updated-since filter).
• Family and leave: smarthr_list_crew_dependents, smarthr_get_crew_dependent, smarthr_list_dependent_relations, smarthr_list_crew_childcare_leaves.
• Accounts: smarthr_list_users and smarthr_get_user (a user is the login, a crew the employee record; embed=crew links them).
• Payroll: smarthr_list_payrolls, smarthr_get_payroll, smarthr_list_payslips, smarthr_get_payslip.
• Writes: smarthr_create_crew, smarthr_update_crew (partial update), smarthr_invite_crew (sends an email, with a form from smarthr_list_crew_input_forms), smarthr_create_department, smarthr_update_department. Show the change and wait for the user's yes. A resignation is an update (emp_status retired, resigned_at), not a delete.

Paging: lists take page and per_page (at most 100, default 10). The answer carries _headers.x-total-count (the total) and _pagination.nextCursor (the next page) until the last page. Ids are UUID strings; dates are YYYY-MM-DD, times ISO 8601.

Limits and errors: 10 requests per second and 5,000 per hour per token, 50,000 per minute per tenant (429 too_many_requests: wait). Errors carry code, type, message and errors per field: 401 unauthorized_token is a wrong or revoked token, 403 a permission the token was not given or a feature the plan lacks (payslips), 404 a wrong id or host, 422 invalid input (read errors).

Switched off at install: smarthr_delete_crew; it cannot be undone, so an admin switches it on when the team needs it.