# 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](/provider-readiness) guide when evaluating HollyHR
for aggregator, warehouse, or internal-platform sync.
Use the [MCP](/mcp) guide when connecting AI clients to the hosted HollyHR MCP
endpoint.
Use [Claude and ChatGPT](/ai-connectors) for client-specific MCP connection
guidance, [AI safety and privacy](/ai-safety-privacy) before connecting
third-party AI clients, [TypeScript SDK](/typescript-sdk) for Node/TypeScript
integrations, and [Sandbox and TTFC](/sandbox) 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](/reference/organisation/guide)
- [People](/reference/people/guide)
- [Org Units](/reference/org-units/guide)
- [Working Patterns](/reference/working-patterns/guide)
- [Time Off](/reference/time-off/guide)
- [Documents](/reference/documents/guide)
- [Custom Fields](/reference/custom-fields/guide)
- [Reference Data](/reference/reference-data/guide)
- [Provider Mappings](/reference/provider-mappings)
- [Exports](/reference/exports/guide)
- [Payroll Readiness Export](/reference/exports/payroll-readiness-export/guide)
- [Webhook Management](/reference/webhooks/guide)

## Recipes

Start with the recipes if you want practical examples:

- [Recipes](/recipes)
- [MCP smoke test](/mcp-smoke)
- [Webhooks](/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:

```text
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.