How to Connect freee人事労務 to an AI Agent
Auth setup
Use the same freee app credentials as accounting. HR API shares the same OAuth token. Easiest: npx freee-mcp handles both domains automatically.
Key facts
| Base URL | https://api.freee.co.jp/hr/api/v1/ |
|---|
| API version | v1 |
|---|
| Auth | Same OAuth 2.0 as freee Accounting (shared MCP server). Register app at freee Developer Portal. The freee MCP server (npx freee-mcp) covers both accounting and HR domains — 28 API files for HR alone. |
|---|
| Token URL | https://accounts.secure.freee.co.jp/public_api/token |
|---|
| Scopes | read,write |
|---|
| Request body | application/json |
|---|
| Pagination | offset: use 'offset' and 'limit' params (max 100). Response includes total_count. |
|---|
| Rate limit | 3,600 requests/hour (shared with accounting API). HR endpoints: same rate pool. |
|---|
| Error format | JSON: {"status_code":400,"errors":[{"type":"validation","messages":["..."]}]} |
|---|
Key endpoints
| Method | Path | Description |
|---|
GET | /employees | List employees with company_id |
GET | /employees/{id} | Get employee detail (profile, dependents, bank account) |
GET | /employees/{id}/time_clocks | Get attendance records (clock in/out) |
POST | /employees/{id}/time_clocks | Record clock in/out |
GET | /employees/{id}/payroll_statements | Get payslips (給与明細) |
GET | /year_end_adjustments/{year}/employees | Year-end adjustment (年末調整) data |
Quickstart
GET /hr/api/v1/employees?company_id=123&limit=10 HTTP/1.1
Host: api.freee.co.jp
Authorization: Bearer {access_token}
Response: {"employees":[{"id":1,"last_name":"田中","first_name":"太郎","num":"EMP001","email":"tanaka@example.com"}]}
Agent pitfalls & tips
- Shares OAuth credentials with freee Accounting — same app, same token, same MCP server.
- company_id required for all endpoints (same as accounting).
- Employee names: last_name/first_name separate fields. Japanese order (姓→名).
- Attendance (勤怠): time_clocks endpoint for raw punch data, work_records for calculated hours.
- Payroll is read-only via API. Payslip generation must be triggered in freee UI.
- Year-end adjustment (年末調整): 28 API files cover the full workflow — from employee data collection to tax document generation.
- Social insurance (社会保険) calculations are automatic based on employee data. Verify employee dependents are up to date.
Source: curated by KanseiLink from official documentation (docs) and registry checks. Last reviewed: 2026-07-06. Specs change — verify against the official docs before production use.
Frequently Asked Questions
What is freee人事労務's AEO score?
▼
freee人事労務 has an AEO score of 0.90 and is rated AA (Strong agent support with minor gaps). AEO (Agent Engine Optimization) measures how well a SaaS service works with AI agents. Scores range from 0.00 to 1.00, with grades from AAA (best) to D (not agent-ready).
Is freee人事労務 AI-agent-ready?
▼
freee人事労務 is currently ✓ verified for AI agent use. It offers an official MCP (Model Context Protocol) server, which means AI agents can connect directly. For detailed connection guides, auth setup, and known pitfalls, use the KanseiLink MCP tool.
How does freee人事労務 compare to other HR & People services?
▼
In the HR & People category, freee人事労務 is rated AA. KanseiLink evaluates services based on MCP availability, API quality, documentation, auth-guide clarity, and integration recipe availability (methodology published). Visit the full rankings at kansei-link.com to see how freee人事労務 compares.
How can I integrate freee人事労務 with an AI agent?
▼
The fastest way to integrate freee人事労務 with an AI agent is through KanseiLink MCP. Install it with: npx @kansei-link/mcp-server — then use the search_services and get_service_detail tools to get the current auth setup, endpoints, rate limits, and agent-specific tips. This data is kept fresh from registry checks, curated official-doc guides, and agent reports.
How do I authenticate with freee人事労務?
▼
Same OAuth 2.0 as freee Accounting (shared MCP server). Register app at freee Developer Portal. The freee MCP server (npx freee-mcp) covers both accounting and HR domains — 28 API files for HR alone. Setup: Use the same freee app credentials as accounting. HR API shares the same OAuth token. Easiest: npx freee-mcp handles both domains automatically.
What are freee人事労務's API rate limits?
▼
3,600 requests/hour (shared with accounting API). HR endpoints: same rate pool.