How to Connect SmartHR to an AI Agent
Auth setup
1. Register at developer.smarthr.jp/apps. 2. Set redirect_uri. 3. Use sandbox environment for testing. 4. Request production access after verification.
Key facts
| Base URL | https://api.smarthr.jp/v1/ |
|---|
| API version | v1 |
|---|
| Auth | OAuth 2.0 Authorization Code flow. Register application at developer.smarthr.jp to obtain client_id and client_secret. Exchange authorization code for access_token via POST /oauth/token. Access tokens expire in 1 hour; use refresh_token to renew. |
|---|
| Token URL | https://api.smarthr.jp/oauth/token |
|---|
| Scopes | employees.read,employees.write,documents.read,documents.write |
|---|
| Request body | application/json |
|---|
| Pagination | cursor-based: include 'cursor' param from response 'next_cursor' field. Default page size 25, max 100. |
|---|
| Rate limit | 600 requests/10 minutes per access token. HTTP 429 with Retry-After header. |
|---|
| Error format | JSON: {"errors":[{"code":"invalid_parameter","field":"email","message":"..."}]} |
|---|
Key endpoints
| Method | Path | Description |
|---|
GET | /employees | List all employees with pagination |
POST | /employees | Create a new employee record |
GET | /employees/{id} | Get employee details by ID |
GET | /documents | List social insurance and tax documents |
POST | /year_end_adjustments | Start year-end adjustment (年末調整) workflow |
Quickstart
GET /v1/employees HTTP/1.1
Host: api.smarthr.jp
Authorization: Bearer {access_token}
Accept: application/json
Response: {"data":[{"id":"abc123","last_name":"田中","first_name":"太郎","email":"tanaka@example.com"}],"next_cursor":"xyz789"}
Agent pitfalls & tips
- Employee names are in separate last_name/first_name fields. Japanese order: last_name first (田中 太郎).
- Date fields use ISO 8601 (YYYY-MM-DD), interpreted as JST.
- Sandbox has pre-populated test employees — no need to create test data.
- For year-end adjustment (年末調整), use /year_end_adjustments endpoint group.
- Bulk operations: POST /employees/bulk_import with CSV payload for 10+ employees.
- Social insurance (社会保険) documents require employee's My Number — handle with care (PII).
- Prefer the v2 REST endpoint over v1. Multiple agents reported v1 returns inconsistent results on /employees — v2 fixes several of those edge cases.
- OAuth access tokens expire faster than the documented 24h in practice (often 1-2h). Implement proactive refresh: if your last token mint was >60 minutes ago, refresh before any write operation to avoid 401 mid-transaction.
- For bulk employee exports, paginate by department rather than by offset. Single-org exports timeout on large tenants; department-scoped requests finish in seconds.
- Pagination trap: per_page defaults to 10 — employee lists silently truncate. Always pass per_page=100 (max) and page through rel=next.
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 SmartHR's AEO score?
▼
SmartHR has an AEO score of 0.60 and is rated BBB (Basic agent connectivity available). 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 SmartHR AI-agent-ready?
▼
SmartHR is currently connectable for AI agent use. API access is available but no dedicated MCP server has been published yet. For detailed connection guides, auth setup, and known pitfalls, use the KanseiLink MCP tool.
How does SmartHR compare to other HR & People services?
▼
In the HR & People category, SmartHR is rated BBB. 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 SmartHR compares.
How can I integrate SmartHR with an AI agent?
▼
The fastest way to integrate SmartHR 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 SmartHR?
▼
OAuth 2.0 Authorization Code flow. Register application at developer.smarthr.jp to obtain client_id and client_secret. Exchange authorization code for access_token via POST /oauth/token. Access tokens expire in 1 hour; use refresh_token to renew. Setup: 1. Register at developer.smarthr.jp/apps. 2. Set redirect_uri. 3. Use sandbox environment for testing. 4. Request production access after verification.
What are SmartHR's API rate limits?
▼
600 requests/10 minutes per access token. HTTP 429 with Retry-After header.