# SmartHR (KUFU, Inc.)

> SmartHR is a Japanese cloud HR platform and system of record for employee data — onboarding and offboarding, social insurance and labour paperwork, payroll slips, withholding tax slips, and organizational structure. The company was founded as KUFU, Inc. and still uses `kufu` as its GitHub organization. The SmartHR API is a tenant-scoped REST API over HTTPS, described by a live Swagger 2.0 document, and is free to existing SmartHR customers.

Generated by the API Evangelist enrichment pipeline on 2026-07-19. SmartHR does not publish an llms.txt of its own; this file is generated from the provider's public documentation and the artifacts in this repository. Documentation is primarily in Japanese.

## API basics

- Base URL: `https://{subdomain}.smarthr.jp/api` — every tenant calls its own subdomain
- Sandbox base URL: `https://{subdomain}.daruma.space/api`
- Version: `v1`, in the URI path
- Auth: `Authorization: Bearer ACCESS_TOKEN` (HTTP Basic with the token as credential is also accepted). Tokens are issued by a tenant administrator in the SmartHR admin dashboard. There is no OAuth 2.0 and no OAuth scopes.
- Content type: `application/json;charset=utf-8`
- Surface: 60 paths, 120 operations, 111 schema definitions

## Documentation

- [Developer portal](https://developer.smarthr.jp/): entry point for API and webhook integration
- [API reference](https://developer.smarthr.jp/api): interactive reference; enter a subdomain and token to try requests
- [API overview](https://developer.smarthr.jp/api/about_api): auth, rate limits, pagination, sorting, error format
- [Sandbox overview](https://developer.smarthr.jp/api/about_sandbox): how to get an isolated test tenant
- [Webhook overview](https://developer.smarthr.jp/api/about_webhook): event catalog and delivery semantics
- [API release notes](https://support.smarthr.jp/ja/release-notes/api/page/1/): dated, API-specific change channel
- [Access token generation](https://support.smarthr.jp/ja/help/articles/360026266033/)
- [Help center](https://support.smarthr.jp/ja/)
- [Security and compliance](https://smarthr.jp/security/)
- [SmartHR Design System](https://smarthr.design/)
- [GitHub organization (kufu)](https://github.com/kufu)

## Specifications

- [OpenAPI (Swagger 2.0)](openapi/kufu-smarthr-openapi.json): served live from `https://app.smarthr.jp/api/v1/swagger_doc`
- [Overlay](overlays/kufu-smarthr-overlay.yaml): API Evangelist enhancements — restores the missing security definitions, records the tenant host template, and attaches runtime semantics

## Conventions

- [Conventions](conventions/kufu-conventions.yml): the cross-cutting rules
- Pagination: `page` (default 1) and `per_page` (default 10, max 100); responses carry an RFC 5988 `Link` header and `x-total-count`
- Sorting: `sort` parameter, comma-separated properties, leading hyphen for descending
- Rate limits: 5,000/hour and 10/second per access token; 50,000/minute per subdomain. State is signalled by `x-rate-limit-*` and `x-intensive-rate-limit-*` headers
- Idempotency: **not supported** — there is no idempotency key, so retried POSTs can duplicate records
- Errors: a custom JSON envelope `{code, type, message, errors}` — **not** RFC 9457 problem+json
- Bulk work is asynchronous: submit a batch job, poll `getV1BatchJobsId`, download output via `getV1BatchJobAttachmentsIdFile`

## Data model

- [Data model](data-model/kufu-data-model.yml): entity-relationship graph derived from the spec
- `Crew` (従業員, employee) is the hub entity; `Dependent`, `Department`, `Payroll`, `Payslip`, `TaxWithholding`, `BizEstablishment` and `User` hang off it
- Records are **bitemporal** — reads return state as of now, and changes can be booked with a future effective date. SmartHR open-sources the same model as [activerecord-bitemporal](https://github.com/kufu/activerecord-bitemporal)
- Tenants extend `Crew` and `Dependent` through typed custom fields rather than a free-form metadata bag

## Events

- [Webhook catalog](asyncapi/kufu-smarthr-webhooks.yml): nine documented events — `crew_created`, `crew_updated`, `crew_deleted`, `crew_imported`, `dependent_created`, `dependent_updated`, `dependent_deleted`, `dependent_imported`, `workflow_approved`
- Delivery is HTTP POST; the configured secret is echoed in the `X-SmartHR-Token` header. There is **no HMAC signature**, so payload integrity cannot be verified
- Retries: ~17 attempts over ~3 days in production, ~5 over ~8 minutes in sandbox; the webhook is disabled once exhausted
- Append `skip_sending_webhook=true` to a write to suppress delivery and avoid feedback loops
- SmartHR publishes no AsyncAPI description

## Security and compliance

- [Vulnerability disclosure](security/kufu-vulnerability-disclosure.yml): responsible disclosure via `security@smarthr.co.jp`, advertised in a PGP-signed [security.txt](well-known/kufu-security.txt). No paid bug bounty
- [Trust center](security/kufu-trust-center.yml): ISO/IEC 27001 (ISMS) certified since 2016-03-22; SOC 2 Type 2 report available to customers on request
- [Domain security](security/kufu-domain-security.yml): TLS 1.3, SPF and DMARC (policy `reject`) on both apex domains; no DNSSEC, no CAA, no HSTS
- [Conformance](conformance/kufu-conformance.yml): what SmartHR does and does not conform to

## Packages

- [Packages](packages/kufu-packages.yml): **SmartHR publishes no official API client SDK.** Its published packages are UI, tooling and Japanese domain-logic libraries
- [Components](components/kufu-components.yml): `smarthr-ui`, an open-source React component library

## Agents

- [MCP server](mcp/kufu-mcp.yml): SmartHR ships none; this repository holds a candidate tool surface derived from the spec
- [Agent skills](skills/_index.yml): packaged flows grounded in real operationIds

## Handling notes for agents

This API is a system of record for regulated Japanese personal data: My Number (individual number), basic pension numbers, bank account details, salary, disability status, and residency documents. Treat every employee payload as sensitive. Prefer read operations; require human confirmation before writes; never route My Number values through an agent context. Because writes are not idempotent, never blind-retry a failed POST — reconcile first.