SmartHR API Deep Dive 2026 — OAuth 2.0, Employee/Year-End-Adjustment Endpoints, and Why the Agent Success Rate Is Stuck at 39%

Why SmartHR is hard to integrate with agents

SmartHR is the flagship of Japanese HR SaaS, covering employee onboarding, document management, social insurance procedures, and year-end adjustment (年末調整). It exposes a comprehensive REST API with a sandbox environment — technically, it's a perfectly integrable platform for agents. And yet KanseiLink's measured agent success rate is only ~39%, with a trust score of 0.6 (as of 2026-05).

This isn't because the API is weak. If anything, the API is well-organized. The problem is that OAuth scope declaration is confusing, and getting it wrong leaves agents stuck on auth_error. On 2026-04-06, in response to the observation that "SmartHR's OAuth scopes are poorly documented and causing auth_error failures," KanseiLink added scope guidance. HR data is a dense mass of personal information, which makes authorization design even more unforgiving — another reason agents stumble.

MCP status — no official MCP, the REST API is the entry point

As of May 2026, SmartHR has no official MCP server (its mcp_status in KanseiLink is api_only). This contrasts with freee HR, which ships an official MCP (npx @freee/mcp-server) in the same HR space. To use SmartHR from an agent, you either (1) call the REST API directly via an HTTP tool, or (2) implement an internal MCP server wrapping the SmartHR API.

Auth — OAuth 2.0 Authorization Code and the scope trap

SmartHR uses an OAuth 2.0 Authorization Code flow. The steps:

1. Register an app at developer.smarthr.jp/apps to obtain client_id / client_secret
2. Set a redirect_uri
3. Send the user through the consent screen, declaring the required scopes, and obtain an authorization code
4. Exchange the code for an access_token via POST https://api.smarthr.jp/oauth/token
5. Send the access_token (nominally expires in 1 hour) as a Bearer token; refresh with refresh_token on expiry

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"}

Key endpoints — employees, documents, year-end adjustment

7 pitfalls in HR-agent development

❌ 1. Misdeclaring OAuth scopes

The number-one failure cause. Declare the exact resource × operation scopes and confirm they pass in the sandbox before going to production.

❌ 2. Sticking with v1

v1's /employees is reported to return inconsistent results in some edge cases, fixed in v2. A legacy employee-list endpoint was deprecated on 2026-02-18, so build new implementations on v2.

❌ 3. Underestimating My Number (social insurance) PII

Social insurance documents require My Number, specially regulated personal information. Never retain it in logs, prompts, or intermediate storage, and limit use to legal purposes. Agents handling My Number should combine least-privilege (documents.read only) with PII masking.

❌ 4. Early token expiry

Nominally 1 hour, but sometimes 1–2 hours in practice. Avoid 401s with proactive refresh before write operations.

❌ 5. Offset-based full export on large tenants

Full employee exports for a single org tend to time out. Agents report that paginating by department finishes in seconds.

❌ 6. Ignoring the rate limit (600 req/10 min)

Roughly 600 req/10 min per token. 429 returns with a Retry-After header — implement exponential backoff honoring that value.

❌ 7. Skipping error-object parsing

Errors take the form {"errors":[{"code":"invalid_parameter","field":"email","message":"..."}]}. Branch on code and field and tell the user which field caused the problem.

vs. freee HR, KING OF TIME, jobcan

"Has an official MCP" and "high success rate" are different things. freee HR has an official MCP but a 50% measured success rate; SmartHR has no official MCP and sits at 39%; API-only Kaonavi is highest at 75%. In HR, what drives success isn't whether an MCP exists — it's how clear the authorization design is and how self-explanatory the errors are. If SmartHR shipped an official MCP and made its OAuth scopes crisp, there's plenty of headroom to lift its success rate toward the level its market share deserves.

Pre-production checklist

• Declaring the minimum necessary OAuth scopes (e.g., employees.read + documents.read) precisely
• Validating scope × endpoint connectivity in the sandbox (sandbox.smarthr.jp)
• Building on v2 endpoints, not v1
• Implementing proactive access_token refresh (refresh first if older than 60 min)
• Applying PII masking that keeps My Number (social insurance documents) out of logs and prompts
• Paginating full exports on large tenants by department
• Implementing exponential backoff honoring the 429 Retry-After header
• Branching on the error response code / field
• Processing names with surname (last_name) first and dates as ISO 8601 (JST)
• Designing retries and idempotency for seasonal workflows like year-end adjustment

FAQ

Q1. Does SmartHR have an official MCP server?

No official MCP as of May 2026 (mcp_status: api_only). Integration runs through the OAuth 2.0-protected REST API. From an agent you call it via an HTTP tool or implement an internal wrapper MCP — in contrast to freee HR, which ships an official MCP.

Q2. Why is the success rate as low as 39%?

The biggest factor is poorly documented OAuth scopes. Misdeclaring scopes returns auth_error, and agents give up without diagnosing the cause. Declaring the right scopes and validating in the sandbox first improves the rate substantially.

Q3. Can agents automate year-end adjustment (年末調整)?

You can start the workflow via the /year_end_adjustments endpoint group. But year-end adjustment is a long-running, regulation-dependent workflow concentrated in December–January, so design around (1) idempotency, (2) retry on failure, and (3) strict handling of PII like My Number.

Q4. What's the minimal setup for an agent touching My Number?

Restrict to least-privilege documents.read only, and separate writes into a different key/flow. Make PII masking mandatory so My Number never lands in logs, prompts, or intermediate storage, and limit use to social insurance and tax procedures.

Q5. v1 or v2 in production?

Prefer v2. v1's /employees is reported to return inconsistent results in some edge cases, fixed in v2. A legacy employee-list endpoint is also deprecated, so confirm the latest v2 paths in the official docs (developer.smarthr.jp/api) at implementation time.