HollyHR Developer Docs
  • Developer platform
  • GitHub
  • Sign in
  • Manage API keys
  • Start Here
  • Core API
  • AI and MCP
  • API Reference
  • Integrations
  • Recipes
  • Resources
ChangelogPlanned changesSupport and feedback
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-11-20

Sick days in the pay-period payroll changes export

Classification: additive

GET /api/v1/payroll-changes-export (payroll_exports:read) returns one more file, payroll-changes-sickness-v1.csv (-v2 for employer packs): one row per sickness absence with days in the period, with first_day_off, last_day_off (blank while still_off is yes), days_off_in_period, working_days_off_in_period and ssp_may_be_due, so payroll can pay Statutory Sick Pay. Person identity matches the other files (person_id for API keys). Dates and counts only: the reason, fit notes and health notes are never included. Existing files and columns are unchanged.

Organisation units use the UK date for "today"

Classification: behavioural

POST /api/v1/org-units without active_from now starts the unit on today's UK date (Europe/London), and GET /api/v1/org-units, the unit lookups and the archive check count a unit as active on the UK date too. Before, both used the UTC date. The two only differ between 00:00 and 01:00 UK time during British Summer Time, when the UTC date is still the day before. Send an explicit active_from (YYYY-MM-DD) if you need a particular day. Scopes, fields and response shapes are unchanged.

2026-11-19

Time off approval respects a recorded leaving date

Classification: behavioural

POST /api/v1/time-off/{timeOffId}/approve and the MCP approve_time_off tool return 422 unprocessable_entity when a request ends after the person's recorded leaving date, with a message explaining how to resolve it. Pending requests for an active person working their notice can still be declined. Existing scope, conditional-write and delegated self-approval checks apply.

2026-11-17

Permanent or fixed-term contracts, with a contract end date

Classification: additive

Employment now says whether a contract is permanent or fixed-term, separately from work_type (full-time, part-time and so on). GET /api/v1/people/{personId}/employment, PATCH on it, the employment history endpoints and the MCP get_person_context and update_person_employment tools carry three new fields:

  • contract_term: permanent, fixed_term, or null when not recorded.
  • contract_end_date: a fixed-term contract's end date, or null. It is not a leaving date: the person stays employed until their employment end_date.
  • contract_end_note: for a fixed-term contract that ends when a task or project is done, or null.

PATCH /api/v1/people/{personId}/employment and POST /api/v1/people/{personId}/employment-history accept all three as a dated change from start_date, so an extension keeps the earlier end date in the history. Setting contract_term to permanent (or null) clears the end date and note. PATCH /api/v1/people/{personId}/employment-history/{historyId} corrects them. An end date or note on a contract that is not fixed-term on that date returns 400 invalid_request with the issue on contract_term.

Disabled Zapier app subscriptions are removed after 30 days

Classification: behavioural

DELETE /api/v1/webhooks/{webhookId} still disables the endpoint, and PATCH with status: "active" still brings it back. New: a REST hook subscription the HollyHR Zapier app created that stays disabled for 30 days, with no retained successful delivery, is removed by HollyHR; GET, PATCH and DELETE on its id then return 404 not_found, and subscribing again creates a new webhook. Webhooks an admin created, and anything your own API client registered (including Zapier catch hooks and Make URLs), are never removed automatically, though an admin can now delete any webhook in Settings. Scopes (webhooks:manage) and tenancy are unchanged. See Webhooks and events.

Delegated access can't decide that person's own time off

Classification: behavioural

POST /api/v1/time-off/{timeOffId}/approve and POST /api/v1/time-off/{timeOffId}/decline (and the MCP approve_time_off and decline_time_off tools) now return 403 permission_denied when the credential is access a person delegated, such as an AI assistant connected as them, and the request is that person's own. Nobody decides their own time off in HollyHR, by any route. An organisation's own API key is unchanged.

Time off can't be moved past a leaving date

Classification: behavioural

PATCH /api/v1/time-off/{timeOffId} (and the MCP update_time_off tool) now returns 422 unprocessable_entity when the change would make the request end after the person's recorded leaving date, the same rule as booking in HollyHR. Changes that leave the dates, day portions, type and quantity alone are unaffected.

Time off and balances work for people without a login

Classification: behavioural

A person created by POST /api/v1/people, or anyone else in HollyHR who has no login yet, can now have time off booked and their balance read and adjusted. Before, these answered 409 conflict "… is not yet available for a person without login access".

  • POST /api/v1/time-off books their time off by the rules HR booking for them in HollyHR follows: their working pattern, bank holidays, leave policy, balance, start and leaving dates; dates back to the start of the previous leave year at most (422 before that); and another leave type can take the days of an office closure that deducts from allowance. It is created approved, as HR's booking for them is: they cannot make a request, so there is nothing to approve. Everyone else's booking still waits for their line manager when they have one.
  • GET /api/v1/people/{personId}/time-off-balance returns their balance, read from their person record as HollyHR shows it.
  • POST /api/v1/people/{personId}/time-off-balance/adjustments adjusts it.
  • PATCH /api/v1/time-off/{timeOffId}, approve and decline work on a pending record of theirs (for example one imported before this change); the person gets no in-app notice of the decision, as they have no login to receive it.
  • GET /api/v1/provider-mappings?resource_type=person&resource_id=… for a real person without a login returns an empty list instead of 400 invalid_request: their person mappings start with their login. An id from another organisation, or a malformed one, is still 400.
  • GET /api/v1/people/{personId}/time-off-balance no longer documents a 409 response; the other routes keep 409 for their other conflicts.

Unknown country codes return 400; time off before a start date or for a leaver returns 422

Classification: behavioural

POST /api/v1/employers and PATCH /api/v1/employers/{employerId} now return 400 invalid_request for a registration_country_code that is two capital letters but not a country (for example HW), with the issue must be a known ISO 3166-1 alpha-2 country code. PATCH /api/v1/people/{personId}/employment and POST /api/v1/people/{personId}/employment-history answer 400 invalid_request "Choose an employment country from the country list" for an unknown employment_country_code. Before, the employer writes returned 500 internal_error.

POST /api/v1/time-off now returns 422 unprocessable_entity when start_date is before the person's employment start date ("Time off can’t start before this person’s employment start date, …"), the same rule as booking in HollyHR; PATCH /api/v1/time-off/{timeOffId} does the same when it moves start_date there. Before, the record was created, and approved at once for someone with no manager. For a person who has left or has a leaving date it now returns 422 with a plain message instead of 404 not_found "Person not found".

Documented: If-Match, 428, a parent 404, required lookup and effective-date fields, and the 409 for people without a login

Classification: additive

The contract now documents what the API already enforced; no request that worked before is refused now.

  • POST /api/v1/people/{personId}/employment-history requires If-Match (the ETag from GET /api/v1/people/{personId}/employment) and documents 412 and 428.
  • PATCH /api/v1/employers/{employerId} documents 428 without If-Match.
  • POST /api/v1/org-units documents 404 for an unknown parent_org_unit_id.
  • GET /api/v1/provider-mappings marks resource_id required.
  • PATCH /api/v1/people/{personId}/employment marks start_date required and describes it as the date the change takes effect.
  • A person created by POST /api/v1/people has no login until they are invited in HollyHR. Until then, time off and balances for them answer 409 conflict; this is now documented on POST /api/v1/time-off, PATCH /api/v1/time-off/{timeOffId}, approve and decline, GET /api/v1/people/{personId}/time-off-balance and balance adjustments.

2026-11-16

Working-pattern times are HH, and writes with times succeed

Classification: behavioural

start_time and end_time on working-pattern days are now HH:mm, as the contract documents, in GET /api/v1/working-patterns, GET /api/v1/working-patterns/{workingPatternId}, write responses and working_pattern.* webhook payloads. Before, they came back as HH:mm:ss, and POST, PATCH and DELETE on a working pattern with times returned 500 internal_error. Working-pattern ETag values change once.

Dates must be real calendar days; bad date filters return 400

Classification: behavioural

Every YYYY-MM-DD request field, for example active_from on POST /api/v1/org-units, must now name a real calendar day; 2026-02-30 returns 400 invalid_request with the issue must be a valid calendar date. Before, some endpoints accepted it and stored the day it rolled over to (2026-03-02). The from and to filters on GET /api/v1/time-off and GET /api/v1/time-off/who-is-out, and created_since with created_until on GET /api/v1/webhooks/{webhookId}/deliveries, now return 400 invalid_request for malformed or impossible values instead of 500 internal_error.

NUL characters and zero balance adjustments return 400

Classification: behavioural

A NUL character (\u0000) in any query parameter or JSON body string now returns 400 invalid_request with the issue must not contain the NUL character (U+0000). Before, for example GET /api/v1/people?search=…, GET /api/v1/time-off?type=…, POST /api/v1/people and POST /api/v1/org-units returned 500 internal_error. POST /api/v1/people/{personId}/time-off-balance/adjustments now returns 400 instead of 500 for an amount that rounds to 0.00 without amount_seconds or to 100,000,000 or more, and for amount_seconds on a category measured in days.

Time off with no working time returns 422, not 500

Classification: behavioural

POST /api/v1/time-off and PATCH /api/v1/time-off/{timeOffId} now return 422 unprocessable_entity when HollyHR cannot work out how much time off the request takes: the dates include no working time for the person, they have no leave policy for those dates, the type is not in their policy, or a company closure already covers the days. The message says what to change, for example "These dates include no working time for this person. Choose dates they work." Before, these requests returned 500 internal_error. MCP writes through commit_api_write return the same unprocessable_entity error.

2026-11-15

Assigned working patterns are no longer edited in place

Classification: behavioural

PATCH /api/v1/working-patterns/{workingPatternId} now returns 409 conflict for a working pattern anyone has been assigned, for any past, current or future period. Its days are the hours those people worked, which leave durations and reports read back, so editing it would silently change them. Create a new working pattern with POST /api/v1/working-patterns and assign that instead. Before, such a pattern with only ended assignments could be edited, and one with a current assignment returned an internal error.

current_assignment_count now counts people on the pattern today or from a later date, including someone whose assignment already has an end date, so it can rise for patterns with scheduled changes. DELETE (archive) keeps returning 409 while that count is above zero.

2026-11-11

Employer register and dated employer fields

Classification: additive

New GET /api/v1/employers, GET /api/v1/employers/{employerId}, POST /api/v1/employers and PATCH /api/v1/employers/{employerId}, behind new employers:read and employers:write scopes. Writes need Idempotency-Key; updates also need If-Match. The register lists companies only, never people.

Employment and employment-history responses add legal_employer, employment_country_code and payroll_handling. PATCH /api/v1/people/{personId}/employment and the employment-history create and correct endpoints accept legal_employer_id, employment_country_code and payroll_handling as dated terms. These writes also need employers:write (403 without it) and confirmed employer setup (409 before it); UK payroll needs country GB, EOR employees cannot be in UK payroll, and a contractor or volunteer cannot be newly given an employer. The hosted MCP server adds list_employers. Employment ETag values change once because the projection gained fields. See the Employers guide.

2026-11-10

Payroll exports separate confirmed employers after optional setup

Classification: behavioural

GET /api/v1/payroll-readiness-export and GET /api/v1/payroll-changes-export retain version-one behaviour until an admin activates optional employer setup. Activated workspaces must pass an opaque, tenant-bound employer_id for one own employer; files and the response use version two with a dated inclusion/exclusion manifest. Confirmed UK employment country and UK payroll handling are required; EOR and external arrangements are excluded, and unresolved facts, transfers or UK eligibility changes at a period boundary, and retrospective corrections block a complete handoff. Incomplete review files retain both arrangements and their dates. Actual employment joining and final leaving dates remain separate from arrangement dates.

Pass gap_report=true to obtain clearly incomplete reports without provider files or granted sensitive values. Existing payroll_exports:read authority and financial-grant restrictions continue to apply. Employer register and assignment endpoints and import fields are not introduced in this phase.

Document type "Driver License" is now "Driving licence"

Classification: behavioural

  • The global document type with id dt_… for driving licences now returns name: "Driving licence" (UK spelling) and description: "UK or other driving licence" from the document type and document endpoints. Its id is unchanged, so clients that match on id are unaffected; clients that match on the old name should match on the id.

Sickness reaches integrations only as a generic absence

Classification: breaking

This is a contract change to time-off records, balances, the balance ledger and time_off.* webhook payloads under time_off:read.

  • A sickness absence now has type: "Absence" and category_id: null in GET /time-off, GET /time-off/{timeOffId}, GET /time-off/who-is-out, time-off write responses and the time_off.* webhook events. Its category name and id are no longer sent. Dates, length and status are unchanged, so a who's-away tool still sees that the person is away, but not the category.
  • category_id is now nullable on time-off records, balance categories and balance-ledger entries.
  • The type filter on GET /time-off matches the public type: a sickness absence matches Absence, never its category name.
  • GET /people/{personId}/time-off-balance no longer returns sick_days_taken. A sickness category in categories is named Absence with a null category_id, and GET /people/{personId}/time-off-balance/ledger reports sickness entries the same way.
  • Writes still refuse sickness records. An approved one gets the same 409 conflict as any approved record; a pending one gets a 409 that does not name sickness.
  • No scope links an absence to the sickness category or returns a sick-day total. Hosted MCP already hid both.
  • TypeScript SDK and Zapier types: category_id is string | null and sick_days_taken is removed.

Retries and redeliveries of events recorded before this change are masked the same way when they are sent. Only sickness is reported as a generic absence, so show it as the person being away, not as a reason. To migrate, treat a null category_id as an absence with no category, and stop reading sick_days_taken.

Clearer MCP tools, typed results and actionable sign-in errors

Classification: behavioural

  • Every hosted MCP tool description now says when to use it and which tool to use instead. Tool names, inputs, scopes and behaviour are unchanged.
  • search_people, get_person, get_person_context, list_time_off, get_time_off, list_reference and whoami now advertise typed output schemas with the exact field names and JSON types they return.
  • An expired, malformed or wrong-audience OAuth access token now gets 401 with WWW-Authenticate: Bearer error="invalid_token" and a message saying how to recover, instead of a 500.
  • The docs now publish a sitemap.xml, and every guide is available as Markdown by adding .md to its URL.

Workspace MCP URLs work with OAuth

Classification: behavioural

  • Adding https://{workspace}.hollyhr.com/api/mcp (or a verified custom domain) to Claude, ChatGPT or another MCP client now completes OAuth instead of failing with invalid_target. The connection always connects that workspace, and fails if the person signing in is not an active member of it.
  • Access tokens keep https://app.hollyhr.com/api/mcp as their audience. A workspace URL accepts only its own workspace's OAuth tokens and answers 401 to any other.
  • Protected-resource metadata on hosts that are neither app.hollyhr.com nor a workspace (for example developers.hollyhr.com) no longer lists authorization_servers; those hosts accept API keys only. app.hollyhr.com metadata and OAuth are unchanged.
  • POST /api/auth/oauth2/authorize must use Content-Type: application/x-www-form-urlencoded; any other media type now gets 415. GET authorization requests are unaffected.

2026-11-09

Revoking an API key disables its webhook endpoints

Classification: behavioural

  • Revoking an API key now disables every active webhook endpoint that key created or changed, and fails their queued deliveries. Deliveries already being sent are checked again just before each one goes out. Each disabled endpoint is recorded in the audit log and can be re-enabled from Integrations > Developer tools > Webhooks or with PATCH /webhooks/{webhookId}. Rotating a key does not disable anything.
  • POST /webhooks, PATCH /webhooks/{webhookId}, and POST /webhooks/{webhookId}/rotate-secret return 401 authentication_required when the key was revoked or expired while the request was in flight.

Rate limits count only failed authentication before a key is checked

Classification: behavioural

  • A valid API key or MCP token no longer spends from a shared pre-authentication bucket, so its documented limit is the real one: 600 requests per minute per organisation, key, and route on the API.
  • Failed authentication is limited to 300 attempts per minute per client IP address (IPv6 per /64) and 60 per minute per credential, for the API and MCP each. A key that authenticated in the last 15 minutes keeps working when its address is over that limit. Junk credentials from other callers can no longer cause 429 responses for your organisation.
  • Hosted MCP exchanges are limited to 600 per minute per organisation and principal, alongside the existing 120 tool calls per minute per tool.

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.
Last modified on November 21, 2026
Planned changes
On this page
  • How to read entries
  • 2026-11-20
    • Sick days in the pay-period payroll changes export
    • Organisation units use the UK date for "today"
  • 2026-11-19
    • Time off approval respects a recorded leaving date
  • 2026-11-17
    • Permanent or fixed-term contracts, with a contract end date
    • Disabled Zapier app subscriptions are removed after 30 days
    • Delegated access can't decide that person's own time off
    • Time off can't be moved past a leaving date
    • Time off and balances work for people without a login
    • Unknown country codes return 400; time off before a start date or for a leaver returns 422
    • Documented: If-Match, 428, a parent 404, required lookup and effective-date fields, and the 409 for people without a login
  • 2026-11-16
    • Working-pattern times are HH, and writes with times succeed
    • Dates must be real calendar days; bad date filters return 400
    • NUL characters and zero balance adjustments return 400
    • Time off with no working time returns 422, not 500
  • 2026-11-15
    • Assigned working patterns are no longer edited in place
  • 2026-11-11
    • Employer register and dated employer fields
  • 2026-11-10
    • Payroll exports separate confirmed employers after optional setup
    • Document type "Driver License" is now "Driving licence"
    • Sickness reaches integrations only as a generic absence
    • Clearer MCP tools, typed results and actionable sign-in errors
    • Workspace MCP URLs work with OAuth
  • 2026-11-09
    • Revoking an API key disables its webhook endpoints
    • Rate limits count only failed authentication before a key is checked
  • 2026-09-09
    • Exact hours-based leave quantities
  • 2026-09-04
    • Provider-resistant webhook lifecycle preconditions
  • 2026-09-02
    • First-party MCP OAuth with stable programmatic principals
  • 2026-09-01
    • Strong resource validators preserved across hosting boundaries
  • 2026-08-30
    • Developer discovery and Smithery ownership reconciled
    • Hosted MCP discovery schemas expanded
  • 2026-08-29
    • Hosted MCP static capability discovery
    • TypeScript SDK preview.5 metadata published
    • Hosted MCP connector ownership discovery hardened
    • Public TypeScript SDK source published
    • TypeScript SDK Public Preview terminology published
    • TypeScript SDK governed decisions published
  • 2026-08-28
    • TypeScript SDK governed-decision preview prepared
    • Glama hosted-connector discovery
    • Governed time-off approval and decline
    • Official hosted MCP discovery repository
  • 2026-08-27
    • Webhook configuration uses optimistic concurrency
    • Canonical geography alongside legacy country fields
    • Public holidays follow configured organisation policy
  • 2026-08-25
    • Governed write access included with paid plans
    • Correlatable API and MCP error diagnostics
  • 2026-08-22
    • Lossless remaining timestamp-cursor pagination
  • 2026-08-21
    • Reliable working-pattern duplicate-name conflicts
    • Lossless People pagination across timestamp boundaries
  • 2026-08-19
    • Truthful hosted MCP executable-surface discovery
  • 2026-08-18
    • Person-bound idempotency for leave-balance adjustments
  • 2026-08-13
    • Active time-off date conflicts
  • 2026-08-06
    • Stable time-off status codes
  • 2026-08-02
    • Effective-dated employment commands replace mutable profile history
  • 2026-08-01
    • Bounded read-event webhooks for instant integrations
    • Minimise hosted MCP absence data
  • 2026-07-30
    • Universal read-only AI connector
    • Governed write-capable AI connectors
    • Newest-first people and time-off polling
  • 2026-07-29
    • Dual-era hosted MCP protocol
  • 2026-07-23
    • Stable domain capability metadata
  • 2026-07-11
    • Opaque person identifiers
  • 2026-07-08
    • Integration readiness
  • 2026-07-06
    • Pay-period payroll changes export
  • 2026-07-01
    • Sandbox API-key environment
  • 2026-06-23
    • TypeScript SDK preview
  • 2026-06-21
    • Metadata discovery
    • Contract lock preparation
  • Deprecation entry format