Copy page

Resources

API Changelog

This changelog records customer-visible changes to the HollyHR public API. HollyHR is currently pre-launch and the public API is in Public Preview, so there are no external-client migrations to announce yet.

How to read entries

Entries are dated by publication date. Each customer-impacting entry should name the affected endpoint, scope, webhook event, SDK package, field family, or docs/runtime surface, and classify the change as one of:

• additive: new endpoint, field, event, docs guide, or helper that should not break existing clients;
• behavioural: compatible behaviour change that clients may want to notice;
• deprecated: an old field, endpoint, event, or behaviour remains available but has a dated replacement path;
• breaking: a removed or incompatible public contract change.

HollyHR has not launched external API consumers yet, so the current entries are launch-readiness records. Machine-readable feeds are generated from this page:

• RSS feed
• Atom feed

Treat this page, those feeds, and Planned changes as the release-communication source of truth.

2026-09-09

Exact hours-based leave quantities

Classification: additive

• Time-off create and pending-update requests accept requested_minutes for an explicit whole-minute quantity on one date when the person's effective policy allows hourly booking. Working-pattern capacity and existing date-overlap protections still apply. No clock-time interval is implied.
• Request responses include nullable requested_minutes and balance_seconds. duration_minutes is requested time; balance_seconds is the exact allowance debit and can be zero for non-consuming leave. Legacy length remains an equivalent-day compatibility field and may be zero for a genuine short request.
• Hour category balances expose signed integer exact_seconds; day categories retain their existing amounts. Ledger responses expose nullable amount_seconds. Balance adjustment writes accept optional non-zero signed amount_seconds for hours, authoritative over the companion decimal amount. For example, use unit: "hours", amount: 0, amount_seconds: -60 for a one-minute correction.
• Use seconds for hour reconciliation, including legacy hundredth-hour remainders (0.01 hour is 36 seconds). Decimal hour amounts and equivalent-day aggregates are display/compatibility values, not substitutes for the exact fields. Never sum days and hours as one allowance.

Existing scopes, tenant authority, idempotency and conditional-write requirements are unchanged. An identical pending request update preserves its original captured working-pattern calculation; changing its scheduling shape requires a fresh quote.

2026-09-04

Provider-resistant webhook lifecycle preconditions

Classification: additive

• PATCH /webhooks/{webhookId} and DELETE /webhooks/{webhookId} now accept HollyHR-Resource-If-Match as a provider-resistant alternative to standard If-Match.
• Send either request header with the exact HollyHR-Resource-ETag returned by GET /webhooks/{webhookId}. Missing, weak, wildcard, or stale validators remain rejected, and standard If-Match remains supported.
• The official Zapier connector uses the provider-resistant header so its REST Hook activation and deactivation requests reach HollyHR through hosting infrastructure that consumes standard HTTP preconditions at the edge.

No webhook payload, signing, scope, tenant, event, idempotency, or concurrency semantics changed.

2026-09-02

First-party MCP OAuth with stable programmatic principals

Classification: breaking

• HollyHR's hosted MCP resource now uses the first-party Better Auth OAuth 2.1 issuer at https://app.hollyhr.com/api/auth instead of the pre-user WorkOS bridge.
• A credential no longer acts as the organisation principal. API keys and OAuth credentials attach to a stable organisation-bound principal whose current grants are intersected with membership, permissions, plan, catalogue and emergency controls on every request.
• New OAuth connections start with the minimal useful read scopes. Write tools challenge for their exact missing scopes and remain subject to System Admin consent, plan eligibility and the existing frozen-payload confirmation flow.
• A new eligible organisation can connect without creating an API key with a special display name. OpenAI and Anthropic use separate reviewer principals.
• Existing pre-user WorkOS review connections must reconnect after the new production path is qualified. HollyHR has no active external MCP customers requiring token migration.

The REST OpenAPI security contract and API-key format are unchanged. The cutover is not live until its exact production SHA passes the empty-tenant, scope-elevation, downgrade, revocation and governed-write qualification.

2026-09-01

Strong resource validators preserved across hosting boundaries

Classification: additive

• Single-resource reads and mutations now return HollyHR-Resource-ETag, an unchanged strong validator for conditional writes, alongside the standard ETag used for HTTP cache validation.
• Raw HTTP clients should send HollyHR-Resource-ETag back as If-Match. This avoids treating a hosting layer's weak cache ETag as write-safe.
• The TypeScript SDK prefers the HollyHR resource validator, retains a standard strong ETag as a compatibility fallback, and returns no response.etag when only a weak cache ETag is present.
• If-Match remains fail closed: missing, weak, wildcard, or stale write validators are not accepted.

2026-08-30

Developer discovery and Smithery ownership reconciled

Classification: additive

• The developer overview now connects the canonical HollyHR bridge, portal, GitHub repositories, Postman workspace, official MCP Registry identity, Smithery listing and Glama connector profile without treating a third-party directory as the source of truth.
• Smithery's apex DNS verification is live, and its authenticated registry API returns hollyhr as a claimed namespace with the managed hollyhr/hollyhr listing.
• Postman remains public with its verified-publisher application under review; Glama remains ingested but publicly unclaimed and untested; OpenAI 1.1.0 remains in provider review. No pending review is described as approved.

No REST, MCP execution, OAuth, scope, request, response, write-confirmation or tenant contract changed.

Hosted MCP discovery schemas expanded

Classification: additive

• Authenticated tools/list and the static GET https://app.hollyhr.com/.well-known/mcp/server-card.json descriptor now publish concise descriptions for every tool input parameter.
• Every registered tool also publishes the structured output schema already enforced by the hosted MCP runtime, so clients can validate and plan tool results without inferring their wrapper shape.
• Static and authenticated discovery use the same canonical input, output, description and safety definitions and are covered by exact equality tests.

Tool names, inputs, execution results, scopes, tenant selection, write posture and human-confirmation behaviour are unchanged. The new schema metadata is content-free and contains no tenant values, credentials or example HR data.

2026-08-29

Hosted MCP static capability discovery

Classification: additive

• GET https://app.hollyhr.com/.well-known/mcp/server-card.json publishes the hosted server identity, OAuth requirement and content-free tool, resource and prompt descriptors for MCP directory scanners.
• Discovery follows the live emergency write posture. Disabling MCP writes removes both write tools, the safe-write resource and the write-review prompt from the card as well as from authenticated MCP discovery.
• The card performs no tenant lookup and exposes no resource body, API key, reviewer credential or HR data.

No REST, MCP execution, OAuth, scope, request, response or write-confirmation contract changed. External directory submission and verification remain separate provider states.

TypeScript SDK preview.5 metadata published

Classification: behavioural

• @hollyhr/api-client@0.1.0-preview.5 is published publicly and is npm latest. Its generated operations and runtime contract are unchanged from preview.4.
• The matching source, generated operation catalogue, runnable examples and versioned OpenAPI contract are tagged at v0.1.0-preview.5.
• npm now links directly to the public source repository, GitHub issue tracker and TypeScript SDK guide. The immutable tarball contains 14 files and reports git head e860f343db70fe82b99322b3299e28786e33c648.

No REST, MCP, Ask Holly, scope, request or response contract changed.

Hosted MCP connector ownership discovery hardened

Classification: additive

• GET https://app.hollyhr.com/.well-known/glama.json now has an explicit cross-origin read policy, bounded stale-while-revalidate caching and an exact contract test for the content-free maintainer record used by Glama.
• The developer guide links the external connector while keeping ingestion, ownership verification and private OAuth testing as separate states.
• No reviewer credential, tenant identifier or HR data is exposed by the route.

No REST, MCP tool, scope, authentication or write contract changed.

Public TypeScript SDK source published

Classification: additive

• The official SDK source, generated operation catalogue, runnable examples and versioned OpenAPI contract are now public at github.com/hollyhr/hollyhr-api-client.
• At initial publication, the repository included CI, contribution and security routes, an explicit release policy and the matching v0.1.0-preview.4 source tag.
• At that point npm latest was 0.1.0-preview.4; preview.5 and its direct repository and GitHub issue metadata are recorded in the later entry above.

No REST, MCP, Ask Holly, scope, request or response contract changed.

TypeScript SDK Public Preview terminology published

Classification: behavioural

• @hollyhr/api-client@0.1.0-preview.4 was published publicly and became npm latest at this point. Its npm README distinguishes the SDK's prerelease lifecycle from HollyHR's Public Preview API.
• Generated operations, examples, runtime behaviour and API contracts are unchanged from 0.1.0-preview.3.
• The immutable public tarball was verified with 14 files, including the generated operation catalogue and governed time-off decision example.

No REST, MCP, Ask Holly, scope, request or response contract changes in this documentation-only SDK correction.

TypeScript SDK governed decisions published

Classification: additive

• @hollyhr/api-client@0.1.0-preview.3 was published publicly and became npm latest at this point.
• Its generated catalogue includes approveTimeOff and declineTimeOff, and the package includes a runnable example that fetches the current ETag before sending If-Match with a fresh idempotency key.
• The immutable public tarball was verified with 14 package files, including compiled JavaScript, declarations, generated operation metadata and checked examples.

No REST, MCP, Ask Holly, scope, request or response contract changed in this publication; the SDK now exposes the governed decision contract that was already live.

2026-08-28

TypeScript SDK governed-decision preview prepared

Classification: additive

• HollyHR has prepared @hollyhr/api-client@0.1.0-preview.3 from the current OpenAPI contract. Its generated catalogue includes approveTimeOff and declineTimeOff, and its package files include a runnable conditional time-off decision example.
• The example fetches the current ETag before sending If-Match and a fresh idempotency key. It requires an explicit approve or decline choice and accepts a private response note only for decline.
• At this point npm latest remained 0.1.0-preview.2; the immutable publication is recorded separately in the 2026-08-29 entry above.

No REST, MCP, Ask Holly, scope, request or response contract changed; the prepared candidate carried the already released contract into the public SDK package.

Glama hosted-connector discovery

Classification: additive

• HollyHR's official hosted MCP is now discoverable in the Glama connector directory under the same io.github.hollyhr/hollyhr identity used by the official MCP Registry.
• GET https://app.hollyhr.com/.well-known/glama.json publishes the public maintainer proof Glama uses to verify ownership of the hosted connector.
• Glama receives non-production reviewer access separately before it runs authenticated capability introspection and produces a quality score. No reviewer credential is included in the public proof or source tree.

No MCP tool, scope, request or response schema changed. This is an additional discovery and verification route for the existing hosted service.

Governed time-off approval and decline

Classification: additive

• POST /v1/time-off/{timeOffId}/approve and POST /v1/time-off/{timeOffId}/decline let an explicitly authorised integration decide one pending standard time-off request.
• Both operations require time_off:write, Idempotency-Key and the current resource ETag in If-Match. Decline accepts an optional private response_note of up to 512 characters.
• Hosted MCP exposes the same operations through the existing prepare, confirm and commit flow. The payload and ETag are frozen before the host asks a person to confirm each action.
• New time_off.approved and time_off.declined webhook events carry the safe time-off projection for decisions made through REST, MCP, Ask Holly and the supported collaboration adapters. Existing app-origin time_off.updated delivery is preserved alongside the more specific event. Private response notes are never included.
• Successful decisions retain the exact API key and request id on the record, immutable status event and audit evidence. API keys are not represented as human managers.

Existing credentials receive no new scopes. A System Admin must still grant time_off:write explicitly, and sickness records remain on their dedicated restricted-health workflow.

Official hosted MCP discovery repository

Classification: additive

• HollyHR's official hosted MCP now has a public discovery repository at github.com/hollyhr/hollyhr-mcp.
• The checked-in server.json matches the live official MCP Registry identity io.github.hollyhr/hollyhr, version 1.0.0, universal endpoint and developer documentation URL.
• The repository documents OAuth discovery, plan availability, explicit scope grants, confirmation-gated writes and the emergency safety boundary. It does not distribute a second server implementation or ask customers to handle a different data plane.

No endpoint, tool, scope, request or response schema changed. The repository is an additional first-party route for clients and directory reviewers to verify and connect the already released hosted service.

2026-08-27

Webhook configuration uses optimistic concurrency

Classification: breaking

• GET /v1/webhooks/{webhookId} now returns a strong ETag and supports If-None-Match with a 304 response.
• PATCH /v1/webhooks/{webhookId} and DELETE /v1/webhooks/{webhookId} now require that current ETag in an If-Match header alongside the existing Idempotency-Key.
• Missing preconditions return 428 precondition_required; stale values return 412 precondition_failed. Successful mutations return the replacement ETag.

HollyHR has no external API consumers yet, so this closes the contract before wider beta rather than imposing a customer migration. New integrations should fetch the webhook immediately before changing it and must not retry a stale write with a fresh idempotency key without reviewing the newer configuration.

Canonical geography alongside legacy country fields

Classification: additive

• Country objects returned by GET /v1/organisation, GET /v1/organisation/locations, GET /v1/people/{personId}/personal, and GET /v1/reference/countries now include an optional geography object.
• geography separates the canonical two-letter country code/name from an optional subdivision code/name. For example, a legacy England row retains country_code: GB-ENG and its existing cty_ id while reporting canonical country GB / United Kingdom and subdivision GB-ENG / England.
• Hosted MCP projections expose the same additive object. Existing ids, names, country codes, scopes, pagination and webhook payloads are unchanged.
• For organisation locations and elevated personal-address reads, geography is now sourced from the canonical country/subdivision stored on the address, rather than being re-inferred from the legacy country row. The outer legacy id, name, and country_code remain unchanged. Organisation-level country and reference-country responses remain on their documented compatibility bridge until their separate facts are migrated.

Clients do not need to migrate. New integrations should prefer geography for address/provider interoperability while HollyHR completes its additive Track B country/subdivision migration. Production rollout of the stored-address read boundary is gated on successful apply and postflight of migration 20260827200951_canonical_address_geography_backfill.

Public holidays follow configured organisation policy

Classification: behavioural

• GET /v1/public-holidays and its hosted MCP operation now read the public holiday calendar selected in Time Off settings instead of the organisation's original signup-country row.
• If public holidays are disabled or the calendar needs configuration, the endpoint returns no dates rather than guessing a country.

The route, year query parameter, response shape and required scope are unchanged. Integrations now receive the same organisation-level calendar dates as the Time Off product surface.

2026-08-25

Governed write access included with paid plans

Classification: behavioural

• Standard and higher plans now satisfy HollyHR's commercial entitlement for public API and MCP write scopes without a separate HollyHR approval step.
• A System Admin must still explicitly select mcp:write and every underlying write scope on the credential. Existing credentials gain no scopes automatically, and the granting admin cannot delegate authority they do not hold.
• MCP writes retain their independent production safety switch and confirmed action controls. This packaging change does not silently activate an operation or weaken its authorisation, audit, idempotency or concurrency requirements.
• Free remains read-only for programmatic access. Public API reads, webhook access and Ask Holly remain included on Free.

No endpoint, request or response schema changed. Standard and higher customers can create a newly scoped credential when the required operation is available; existing credentials continue with their current scopes.

Correlatable API and MCP error diagnostics

Classification: behavioural

• Authenticated public API error responses now retain the consumed route bucket's RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. When a more specific rate-limit failure supplies its own bucket metadata, that metadata continues to take precedence.
• Hosted MCP structured tool errors now include the opaque request_id stored with the corresponding HollyHR request log, so customers can provide one identifier when asking for help with a failed tool call.
• Error codes, HTTP statuses, scope checks, data projections and rate-limit budgets are unchanged.

Clients do not need to migrate. Integrations may record the returned request ID and rate-limit headers for diagnostics and retry decisions.

2026-08-22

Lossless remaining timestamp-cursor pagination

Classification: behavioural

• For a stable result set, GET /v1/documents, timestamp-sorted GET /v1/time-off, and GET /v1/people/{personId}/employment-history cursors no longer skip or repeat records solely because stored timestamps differ below millisecond precision.
• Cursor comparison and ordering now use the same millisecond precision as the existing opaque cursor. Time Off retains both updated_since directions, and all three endpoints retain their existing ID tie-breakers.
• Existing cursor strings remain accepted. Lossless traversal is guaranteed when the resumed cursor was produced under this normalized ordering; a page paused across the deployment boundary can retain the prior ordering's sub-millisecond ambiguity. Request parameters, response fields, OpenAPI schemas, and SDK method signatures are unchanged.

Clients do not need to migrate. Concurrent mutations retain normal keyset pagination semantics and do not create a snapshot across requests.

2026-08-21

Reliable working-pattern duplicate-name conflicts

Classification: behavioural

• POST /v1/working-patterns and PATCH /v1/working-patterns/{workingPatternId} now preserve the standard conflict error with HTTP 409 when concurrent writes race to use the same organisation-scoped working-pattern name.
• The response remains content-free and does not expose database query text, parameters, constraint details, or another working pattern.

Request and response schemas are unchanged. Clients may keep the draft and ask the user to choose a different working-pattern name.

Lossless People pagination across timestamp boundaries

Classification: behavioural

• For a stable result set, GET /v1/people cursors no longer skip or repeat people solely because stored timestamps differ below millisecond precision.
• The default created-at order, sort=updated_at_desc, and both directions of updated_since pagination use the same millisecond timestamp precision as the existing opaque cursor.
• Existing cursor strings remain valid. Request parameters, response fields, OpenAPI schemas and SDK method signatures are unchanged.

Clients do not need to migrate. Integrations that previously stopped after a submillisecond-precision empty page or encountered a precision-induced repeated page can continue following pagination.next_cursor until pagination.has_more is false. Concurrent mutations retain normal keyset pagination semantics and do not create a snapshot across requests.

2026-08-19

Truthful hosted MCP executable-surface discovery

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.

At this release, the public REST API, OpenAPI contract, TypeScript SDK, MCP field projections and default-off write posture were unchanged. The later 2026-08-25 packaging entry records Standard+ governed-write availability. Clients should treat tools/list as the callable tool-name authority and the operation catalogue as generic-call capability metadata.

2026-08-18

Person-bound idempotency for leave-balance adjustments

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.

2026-08-13

Active time-off date conflicts

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.

2026-08-06

Stable time-off status codes

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.

2026-08-02

Effective-dated employment commands replace mutable profile history

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.

2026-08-01

Bounded read-event webhooks for instant integrations

Classification: behavioural

• At this release, webhooks:manage and bounded signed read-event delivery became available on every plan. Event families still required the corresponding read scope, while programmatic employee writes required Standard plus exact HollyHR approval. The later 2026-08-25 packaging entry removes that HollyHR approval gate while preserving explicit admin scope grants.
• 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.

Minimise hosted MCP absence data

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.

2026-07-30

Universal read-only AI connector

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.

Governed write-capable AI connectors

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.

Newest-first people and time-off polling

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.

2026-07-29

Dual-era hosted MCP protocol

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.

2026-07-23

Stable domain capability metadata

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.

2026-07-11

Opaque person identifiers

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.

2026-07-08

Integration readiness

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.

2026-07-06

Pay-period payroll changes export

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.

2026-07-01

Sandbox API-key environment

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.

2026-06-23

TypeScript SDK preview

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.

2026-06-21

Metadata discovery

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.

Contract lock preparation

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.

Deprecation entry format

Future deprecation or breaking-change entries should include:

• the date the change was published;
• the endpoint, scope, webhook event, or field affected;
• whether the change is behavioural, deprecated, or breaking;
• the effective date for any deprecation or sunset;
• the migration path and final failure mode.
• the response headers, SDK warning, webhook version, or docs pointer clients can use to detect the transition where applicable.