Copy page

Start Here

HollyHR API Overview

HollyHR's public API, signed webhooks and hosted MCP are in Public Preview. Organisation-scoped reads are available on every plan. Bounded signed-webhook management is also included; programmatic writes are included on Standard and higher plans without a separate HollyHR approval. A System Admin must explicitly select every write scope, and hosted MCP retains its independent production activation and confirmation controls. System Admins manage the scoped API keys used to connect HollyHR data to internal tools, reporting jobs, and lightweight automations.

The Public Preview is intentionally focused. It covers the surfaces that are already implemented and protected by generated OpenAPI contracts:

• API-key context with /me
• live-environment testing guidance
• people directory reads and incremental sync
• safe people setup with POST /people
• conditional safe setup-field updates with PATCH /people/{person_id}
• safe lifecycle actions with POST /people/{person_id}/end and POST /people/{person_id}/reactivate
• safe employment writes with PATCH /people/{person_id}/employment and POST /people/{person_id}/employment-history
• elevated personal profile reads with GET /people/{person_id}/personal
• org-unit reads and safe org-unit setup writes, plus person org-link reads
• reference data
• time-off records, public holidays, and safe pending-request create/update/approve/decline/cancel writes
• document metadata
• safe payroll readiness export for payroll/accounting review and bureau handoff
• outbound webhook management, secret rotation, synthetic test delivery, public API-origin events for implemented writes, and selected app-origin people and time-off events where the domain-event spine is wired
• machine-readable API metadata discovery for routes, fields, scopes, and webhook event requirements
• provider-style readiness guidance for people, employment, org-unit, time-off, custom-field, working-pattern, and webhook sync
• a generated public-preview TypeScript SDK package for Node, Next.js, workers, and scripts
• a Public Preview hosted MCP endpoint at /api/mcp for AI clients using scoped API keys
• agent-readable discovery at /auth.md
• a time-to-first-call smoke harness for API + MCP connectivity checks

The default API projections do not expose home addresses or dates of birth. Those fields are available only through the separate elevated people:personal:read scope. The API does not expose document bytes, demographics, bank details, compensation, tax or government identifiers.

Public Preview boundaries

The current write surface is limited to safe people setup, safe setup-field updates, safe people lifecycle actions, safe employment writes, safe org-unit setup writes, and safe pending time-off request create/update/approve/decline/cancel writes. Edits to approved/taken/cancelled records, sickness decisions, person org-link writes, stored time-off notes/reasons, comprehensive UI-origin/domain-wide webhook emission, payroll-specific employment detail, SCIM, delegated OAuth partner apps, reports, signed document downloads, and native partner integrations are not part of this Public Preview surface.

The first-party Xero Payroll UK connection is product functionality rather than a public API endpoint. Its provider OAuth grant is not exposed to API keys or MCP clients.

Use the Webhooks guide for setup, signing, retry, and event-delivery behaviour. Use API modules for a quick map of the implemented public API surface, scopes, webhook posture, and Public Preview boundaries. Use the Provider readiness guide when evaluating HollyHR for aggregator, warehouse, or internal-platform sync. Use the MCP guide when connecting AI clients to the hosted HollyHR MCP endpoint. Use Claude and ChatGPT for client-specific MCP connection guidance, AI safety and privacy before connecting third-party AI clients, TypeScript SDK for Node/TypeScript integrations, and Sandbox and TTFC when proving a disposable tenant. Use Fields and metadata when a response omits a field, an integration needs scope/field discovery, or tenant-specific custom fields need to be resolved. Use the API reference for the exact implemented endpoints, fields, query parameters, and error responses. The reference is generated from HollyHR's Zod contracts and checked in CI so it stays aligned with the application. Use GET /metadata when an integration needs a machine-readable catalogue of routes, required scopes, path/query parameters, schema fields, field categories, and webhook event scope requirements generated from the same contract source.

Public developer surfaces

Use HollyHR's first-party surfaces as the source of truth, then use the public directories when their import or discovery workflow is useful:

• Developer overview for the product-level API, MCP and automation story.
• Developer portal for guides, generated API reference and the downloadable OpenAPI contract.
• HollyHR on GitHub for public discovery, examples and SDK source.
• MCP discovery repository for the hosted endpoint, OAuth discovery, scopes and governed-write safety.
• API and MCP examples for runnable integration recipes.
• TypeScript SDK and versioned OpenAPI for source, issues and pinned contracts.
• Postman public workspace for ready-to-fork collections.
• Official MCP Registry identity io.github.hollyhr/hollyhr, with machine-readable Registry readback.
• Smithery for its managed hosted-directory route and Glama for its Registry-ingested connector profile.

Third-party listings do not replace the first-party documentation. Check their verification state before treating a badge or catalogue entry as an endorsement.

API Reference Guides

Use the guides inserted into the API reference when you want the product-domain view of a reference group: scopes, field posture, common workflows, Public Preview limits, and links into generated endpoint schemas.

• Organisation
• People
• Org Units
• Working Patterns
• Time Off
• Documents
• Custom Fields
• Reference Data
• Provider Mappings
• Exports
• Payroll Readiness Export
• Webhook Management

For the first-party approved-leave connection, use the Xero Payroll UK guide.

Recipes

Start with the recipes if you want practical examples:

• Recipes
• MCP smoke test
• Webhooks

These examples are custom workflows that either read from the Public Preview API or receive Public Preview webhook events. Built-in calendar feeds for Google Calendar, Outlook, and Apple Calendar are available inside HollyHR from the Who's Away page and do not require the public API.

Base URL

Use the same HollyHR app origin your organisation signs in to:

Code
https://{workspace}.hollyhr.com/api/v1

If your organisation uses a custom HollyHR domain, use that app origin with the same /api/v1 path. Local and preview environments use their own app origin with the same path.