Copy page

Start Here

HollyHR API Overview

HollyHR's public API is in beta and available to Pro organisations. It gives System Admins a documented way to connect HollyHR data to internal tools, reporting jobs, and lightweight automations.

The beta API is intentionally narrow. 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/cancel writes
• document metadata
• safe payroll readiness export for payroll/accounting review and bureau handoff
• outbound webhook management, secret rotation, synthetic test delivery, and public API-origin events for implemented writes
• 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 TypeScript SDK package for Node, Next.js, workers, and scripts
• a 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.

Beta 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/cancel writes. Time-off approval or rejection, edits to approved/taken/cancelled records, person org-link writes, time-off notes/reasons, 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 beta surface.

Use the Webhooks guide for setup, signing, retry, and event-delivery behaviour. 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 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.

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, beta 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

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 beta API or receive beta 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.