https://developers.hollyhr.com/changelog 2026-08-19T00:00:00Z https://developers.hollyhr.com/changelog#truthful-hosted-mcp-executable-surface-discovery 2026-08-19T00:00:00Z 2026-08-19T00:00:00Z

Classification: behavioural Hosted MCP operation discovery now reports one explicit execution disposition for every public API operation: executable, policy-blocked, missing a reviewed MCP projection, missing an MCP dispatcher, or disabled by the live write mode. The embedded alias catalogue distinguishes real tools/list registrations from conceptual aliases that remain available only through generic operation tools. No alias, operation, scope or data projection has been added. Compound aliases are advertised only when the authenticated principal can call every constituent operation. In particular, get_person_context requires both people:read and time_off:read in discovery as well as at execution. The public REST API, OpenAPI contract, TypeScript SDK, MCP field projections and default-off write posture are unchanged. Clients should treat tools/list as the callable tool-name authority and the operation catalogue as generic-call capability metadata.

https://developers.hollyhr.com/changelog#person-bound-idempotency-for-leave-balance-adjustments 2026-08-18T00:00:00Z 2026-08-18T00:00:00Z

Classification: behavioural POST /v1/people/{personId}/time-off-balance/adjustments now binds the target personId into its idempotency fingerprint. Reusing one idempotency key and request body for a different person now returns the standard HTTP 409 idempotency conflict instead of replaying the first person's stored success response. Same-person retries remain idempotent. Unexpired receipts created before this change are replayed only after HollyHR validates that the stored adjustment belongs to the requested person and organisation. Clients should use a distinct idempotency key for each intended person-level adjustment. No request or response schema changed.

https://developers.hollyhr.com/changelog#active-time-off-date-conflicts 2026-08-13T00:00:00Z 2026-08-13T00:00:00Z

Classification: behavioural POST /v1/time-off and PATCH /v1/time-off/{timeOffId} now return the standard conflict error with HTTP 409 when any selected date overlaps the person's pending or approved standard time off. The response remains content-free: it does not identify the conflicting record or expose its category, notes, or sickness state. Clients should preserve the draft and ask the user to choose different dates.

https://developers.hollyhr.com/changelog#stable-time-off-status-codes 2026-08-06T00:00:00Z 2026-08-06T00:00:00Z

Classification: additive Public time-off list and item responses now include status_code with one of pending, approved, rejected, or cancelled. The existing human-readable status field remains available for display; clients should use status_code for workflow logic. No customer action is required.

https://developers.hollyhr.com/changelog#effective-dated-employment-commands-replace-mutable-profile-history 2026-08-02T00:00:00Z 2026-08-02T00:00:00Z

Classification: breaking PATCH /v1/people/{personId} is now identity-only. Employment changes use the dedicated employment and employment-history routes. Current-employment changes and new history facts require an effective start_date, If-Match, and Idempotency-Key. History updates are factual corrections, require correction_reason, and return a new immutable fact. Ending employment records an inclusive final day. Reactivation is now a true rehire and requires a new start_date after the prior period. Employment and history responses include timeline_version; their ETags are bound to that version so a correction that leaves visible terms unchanged still invalidates a stale write. HollyHR remains pre-launch with no external API consumers, so the beta contract and generated SDK move directly to this canonical model without a legacy compatibility period.

https://developers.hollyhr.com/changelog#bounded-read-event-webhooks-for-instant-integrations 2026-08-01T00:00:00Z 2026-08-01T00:00:00Z

Classification: behavioural webhooks:manage and bounded signed read-event delivery are now available on every plan. Event families still require the corresponding read scope; programmatic employee writes remain Standard plus exact HollyHR approval. New deliveries get a best-effort request-context fast attempt. A fair one-minute durable worker remains authoritative for retries and recovery. Each organisation may have up to 10 active endpoints, 500 pending deliveries per endpoint and 5,000 pending deliveries in total. Lifecycle mutations have dedicated API-key and organisation limits; overload is recorded explicitly and disables the affected endpoint rather than silently dropping rows. Person events now include public-projection employment edits and committed spreadsheet imports. Bulk imports retain durable recovery without scheduling hundreds of request-lifetime callbacks. Existing webhook URLs, signing, event envelopes and read-scope requirements are unchanged. No customer action is required.

https://developers.hollyhr.com/changelog#minimise-hosted-mcp-absence-data 2026-08-01T00:00:00Z 2026-08-01T00:00:00Z

Classification: behavioural Hosted MCP time-off-balance results no longer include explicit sickness totals. Ordinary leave totals remain available; raw absence categories, medical content and joinable category identifiers remain excluded. The public REST API, OpenAPI contract and TypeScript SDK are unchanged. No customer action is required.

https://developers.hollyhr.com/changelog#universal-read-only-ai-connector 2026-07-30T00:00:00Z 2026-07-30T00:00:00Z

Classification: additive https://app.hollyhr.com/api/mcp is now the canonical connector URL for Anthropic and OpenAI directory clients. The authenticated principal, never a hostname or tool argument, selects the HollyHR workspace. The initial provider listing is read-only. Its fixed synthetic reviewer actor has seven read scopes and no write scopes; disabled mode removes write tools, prompts and advertised write scopes. WorkOS-backed OAuth discovery advertises only the identity scopes that WorkOS issues. HollyHR data permissions remain enforced by the bound, tenant-scoped backing actor rather than being requested from the identity provider. Provider review uses eight durable cases—five positive and three adversarial—with expected tenant, projection and no-mutation outcomes. list_api_operations omits the optional required_scope field when an operation has no single REST scope, preventing remote MCP clients from rejecting an otherwise valid catalogue response. Tenant-origin MCP URLs remain available for existing server-side integrations. No customer action is required.

https://developers.hollyhr.com/changelog#governed-write-capable-ai-connectors 2026-07-30T00:00:00Z 2026-07-30T00:00:00Z

Classification: behavioural HollyHR's hosted MCP server now advertises write tools and write OAuth scopes only while the production write mode is enabled. Disabling the mode removes them from discovery as well as rejecting execution. Supported writes remain limited to the positively projected People and Time Off operations in the public API catalogue. A write is first frozen into an exact preview and can commit only after explicit host-mediated approval. Read, prepare, and commit tools now carry complete MCP annotations so connected assistants can distinguish non-mutating calls from changes that require confirmation. OAuth directory reviewers use a fixed synthetic Sandbox identity with no access to customer records. Workspace identity, actor scopes, field projections, ETag checks, idempotency, audit, revocation, and PII budgets continue to apply. No customer action is required. Workspace administrators retain control of connector credentials and write scopes.

https://developers.hollyhr.com/changelog#newest-first-people-and-time-off-polling 2026-07-30T00:00:00Z 2026-07-30T00:00:00Z

Classification: additive GET /people and GET /time-off now accept sort=updated_at_desc to return the most recently updated records first. The existing default order is unchanged when sort is omitted. Descending responses retain cursor pagination and the same tenant, scope, plan, field-projection, and rate-limit boundaries as the existing lists. The generated OpenAPI contract and TypeScript SDK expose the new query option. This option is intended for polling integrations that need to process recent changes first. No customer action is required.

https://developers.hollyhr.com/changelog#dual-era-hosted-mcp-protocol 2026-07-29T00:00:00Z 2026-07-29T00:00:00Z

Classification: additive POST /api/mcp now prefers the stateless 2026-07-28 protocol while continuing to accept stateless 2025-11-25 initialize clients. Both protocol eras use the same hosted endpoint, bearer authentication, tenant principal, tools, projections, masking, PII budget and request audit. Governed writes use modern input_required approval before the existing signed frozen write can commit. Stateless legacy clients can read and prepare but fail closed at commit because they cannot carry host approval. The repository pnpm mcp:smoke command verifies both protocol eras. No customer action is required. New integrations should prefer 2026-07-28; clients that still default to 2025-11-25 remain compatible.

https://developers.hollyhr.com/changelog#stable-domain-capability-metadata 2026-07-23T00:00:00Z 2026-07-23T00:00:00Z

Classification: additive Every generated OpenAPI operation now includes x-hollyhr-domain-capabilities. GET /metadata and the hosted MCP catalogue expose the same stable domain capability identifiers for discovery and cross-surface tooling. Capability metadata does not grant authority: REST scopes, API-key or OAuth principals, MCP projections, masking, and write confirmation remain independently enforced. No customer action is required.

https://developers.hollyhr.com/changelog#opaque-person-identifiers 2026-07-11T00:00:00Z 2026-07-11T00:00:00Z

Classification: breaking Person-facing API resources, references, webhooks, and exports now use tenant-specific opaque 12-character person_id values. Legacy numeric user IDs are no longer accepted as person identifiers. The same individual has a different person identifier in each organisation; identifiers remain locators rather than authorisation tokens. The public API is pre-launch beta. Update any internal fixtures or preview integrations that retained numeric person IDs by resolving people again through GET /people.

https://developers.hollyhr.com/changelog#integration-readiness 2026-07-08T00:00:00Z 2026-07-08T00:00:00Z

Classification: additive Added GET /integration-readiness for tenant-scoped payroll, accounting, and spend-tool readiness. The response reports aggregate readiness, issue severity, and provider playbooks without exposing raw payroll-financial, banking, receipt, or provider-secret values. Generated OpenAPI, metadata, and TypeScript SDK contracts include the new operation. No customer action is required.

https://developers.hollyhr.com/changelog#pay-period-payroll-changes-export 2026-07-06T00:00:00Z 2026-07-06T00:00:00Z

Classification: additive Added GET /payroll-changes-export?from=YYYY-MM-DD&to=YYYY-MM-DD for inclusive periods of up to 400 days. The export covers starters, leavers, safe employment-history changes, and compensation or banking change flags; it never exports salary amounts, percentages, bank-account fields, or free-text reasons. The operation requires payroll_exports:read and is deliberately excluded from the hosted MCP catalogue. No customer action is required.

https://developers.hollyhr.com/changelog#sandbox-api-key-environment 2026-07-01T00:00:00Z 2026-07-01T00:00:00Z

Classification: additive API keys created in HollyHR's platform-owned synthetic sandbox use the hhr_test_ prefix; ordinary tenant keys continue to use hhr_live_. GET /me now reports environment.type and environment.sandbox so integrations can prove which tenant environment owns a key before doing work. The OpenAPI Try-It configuration and developer guides expose the real sandbox environment without implying that live customer tenants are cloned. No customer action is required.

https://developers.hollyhr.com/changelog#typescript-sdk-preview 2026-06-23T00:00:00Z 2026-06-23T00:00:00Z

Classification: additive Published the beta @hollyhr/api-client package to npm with generated, typed operations from the public OpenAPI contract. Added runnable TypeScript examples and package drift checks so the SDK, OpenAPI, and runtime operation catalogue remain aligned. No customer action is required.

https://developers.hollyhr.com/changelog#metadata-discovery 2026-06-21T00:00:00Z 2026-06-21T00:00:00Z

Classification: additive Added GET /metadata, a machine-readable catalogue of public API routes, required scopes, path/query parameters, schema fields, field categories, and webhook event scope requirements. The catalogue is generated from the same OpenAPI/Zod contract source as the public reference. No customer action is required.

https://developers.hollyhr.com/changelog#contract-lock-preparation 2026-06-21T00:00:00Z 2026-06-21T00:00:00Z

Classification: additive Documented the v1 error envelope as the public API error contract. Documented public API rate-limit headers and default request buckets. Added planned-changes, support, feedback, and OpenAPI import guidance to the developer docs. No customer action is required.