Core API
API Modules
Use this map to choose the right HollyHR API surface before opening the full reference. The reference remains the source of truth for exact schemas, status codes, headers, and examples.
HollyHR's public API is in governed Public Preview, not a full clone of every HRIS module. Current endpoints focus on safe HR sync, setup automation, provider readiness, and AI-accessible workflows that can be scoped and audited before launch.
Module map
| Module | Available today | Primary scopes | Webhook posture | Public Preview boundary |
|---|---|---|---|---|
| API key context | GET /me for caller, organisation, scope, and environment discovery. | Any valid API key. | None. | No OAuth partner-app registration in Public Preview. |
| Metadata | GET /metadata for routes, scopes, parameters, schema fields, field categories, and webhook event requirements. | Any valid API key. | None. | Metadata describes the public contract; it does not expose tenant data or unsupported fields. |
| Organisation | Organisation details and active locations. | organisation:read | None. | No public organisation mutation or billing/admin model. |
| People | Directory list/detail, safe person setup, lifecycle actions, current employment, employment history, personal-profile detail, avatar signed URL detail, time-off balance links, and org-link reads. | people:read, people:write, people:personal:read, people:avatar:read, time_off:read for balances. | Public API-origin person.* events for implemented writes; app-origin person create/update where the domain-event spine is wired. | No SCIM, invite email, access-role reads, demographics, compensation, bank, tax, government id, or document bytes. |
| Org units | Canonical organisation-structure reads and safe setup/lifecycle writes for departments, teams, divisions, cost centres, legal entities, and location groups. | org_units:read, org_units:write | Public API-origin org_unit.* events. | Person org-link writes, UI-origin org-unit events, and org-chart mutation semantics remain future work. |
| Working patterns | Weekly and cycle-based working-pattern templates plus current assignment context. | working_patterns:read, working_patterns:write | Public API-origin working_pattern.* events. | Working-pattern fields are HR context, not payroll certification. |
| Time off | Records, settings, public holidays, categories, balances, balance adjustments, and safe pending-request create/update/approve/decline/cancel. | time_off:read, time_off:write, time_off:config:write, time_off:balance:write | time_off.*, time_off_category.*, and time_off_settings.updated; governed app, API, MCP, Ask Holly and collaboration decisions emit specific approval/decline events. | No edits to approved/taken/cancelled records, no sickness decisions, and no stored notes/reasons. |
| Custom fields | API-visible person custom-field definitions and person values. | custom_fields:read, custom_fields:write | No dedicated custom-field event family in Public Preview. | Definitions are managed in HollyHR; no public definition writes, multi-select fields, or non-person custom fields. |
| Reference data | Global and tenant dictionaries for countries, statuses, work types, work places, document types, and time-off categories. | reference:read, time_off:config:write | Time-off category writes emit public API-origin category events. | No generic named-list/table API. Use Custom Fields and Metadata for API-visible person fields. |
| Documents | Document metadata list/detail and document-type reference data. | documents:read, reference:read | None. | Metadata only; no document bytes, signed downloads, uploads, e-sign, folders, or write APIs. |
| Provider mappings | Active external/provider id reconciliation metadata. | provider_mappings:read plus the matching resource read scope. | None. | No raw provider payloads, deleted mapping history, or provider write APIs. |
| Exports | Provider-neutral payroll-readiness export with manifests and sensitive-field presence signals. | payroll_exports:read | None. | Not a payroll API: no salary, bank, tax, NI, payroll-run, payslip, or statutory-pay data. |
| Webhooks | Endpoint management, secret rotation, synthetic test delivery, health, delivery logs, and manual redelivery. | webhooks:manage plus event resource read scopes. | Signed outbound delivery with bounded retries and retained delivery telemetry. | Events are in Public Preview; source coverage varies by event family, so use the relevant guide before promising real-time sync. |
| MCP and AI | Hosted MCP endpoint and AI connector guidance over organisation-bound API-key or OAuth principals. | Read tools use the matching REST scopes; write tools also require mcp:write and the enabled MCP write-mode gate. | Uses existing REST/webhook contracts rather than a separate data plane. | AI clients do not bypass scopes, Public Preview boundaries, or sensitive-field posture. |
Not hidden endpoints
The following are not available through undocumented public endpoints:
- attendance and clock-in/clock-out;
- hiring, ATS, onboarding tasks, learning, goals, benefits, expenses, and performance modules;
- generic report builders or async report-run APIs;
- payroll, compensation, bank, tax, government-identifier, or payslip APIs;
- document bytes, signed downloads, uploads, e-sign, and document write APIs;
- SCIM provisioning or delegated OAuth partner applications.
Those areas need separate product, privacy, support, and commercial decisions. HollyHR's current stance is to document the boundary clearly rather than imply coverage that does not exist.
Choosing a surface
- Use Provider readiness when evaluating an aggregator, warehouse, bureau, or internal-platform sync.
- Use Expense and spend tools when syncing people, departments, cost centres, legal entities, and leaver context into Xero Expenses, FreeAgent, Dext, Pleo, Soldo, Expensify, Zoho Expense, or a similar specialist finance/spend system.
- Use Fields and metadata when a response omits a field, a custom field is hidden, or an integration needs machine-readable route/scope discovery.
- Use the reference guides under API Reference when you need the product-domain details for one module.
- Use Planned changes to distinguish committed launch work from future candidates.
Last modified on