Copy page

Core API

Provider readiness

HollyHR's beta API is built for provider-style sync, internal reporting jobs, and lightweight automation. This page explains what an integrator can rely on today and where the beta boundary is.

Use the API reference for exact schemas. It is generated from the same contracts the application uses.

Ready today

Area	What you can sync
People	Directory rows, person details, manager links, status, job title, start/end dates, department/org-unit summaries, work-place, work-type, working-pattern/FTE context.
Personal profile	Date of birth, personal contact, and home address for one person at a time with people:personal:read.
Employment	Current employment context, safe employment updates, and employment-history creation.
Organisation	Organisation/account details and active locations.
Org units	Canonical organisation-structure reads and safe org-unit writes for departments, teams, divisions, cost centres, legal entities, and location groups. Person memberships and reporting links are read-only.
Working patterns	Weekly and cycle-based working-pattern templates plus current assignment context.
Time off	Records, pending-request writes, settings, categories, balances, and balance adjustments.
Custom fields	Person custom-field definitions and values with explicit custom-field scopes.
Provider mappings	Active external/provider ID mappings for bounded reconciliation lookups. Requires provider_mappings:read plus the relevant resource read scope.
Payroll export	Elevated provider-neutral payroll readiness package with operational employment/org/working-time fields and sensitive-field presence flags.
Documents	Metadata only. Document bytes and signed downloads are not in beta.
Webhooks	Endpoint management, secret rotation, test delivery, retries, signing, and public API-origin write events.

Scope model

Start with the smallest scope set that fits your workflow.

Scope family	Use it for
people:read	Operational directory and employment context.
people:personal:read	Detail-only personal profile reads for a named person.
people:write	Safe setup, setup-field, lifecycle, and employment writes.
custom_fields:read / custom_fields:write	Person custom-field definitions and values.
time_off:*	Time-off records, settings, balances, and supported adjustments.
org_units:read	Org-unit reads, hierarchy, lifecycle fields, and provider ids.
org_units:write	Safe org-unit setup writes and lifecycle actions.
working_patterns:*	Working-pattern template and assignment workflows.
provider_mappings:read	Active provider/remote ID reconciliation metadata. Also requires the relevant resource read scope.
payroll_exports:read	Elevated payroll readiness package with sensitive presence flags.
webhooks:*	Webhook endpoint management and delivery testing.

Base people responses do not include personal contact, home address, date of birth, demographics, compensation, bank details, tax or government identifiers, document bytes, or avatar bytes.

Common sync patterns

People directory sync

1. Request people:read.
2. Call GET /people with cursor pagination.
3. Store HollyHR person_id as the stable HollyHR id in your downstream cache.
4. Use updated_since for incremental sync.
5. Fetch GET /people/{personId} only when you need a detail view.

Use GET /provider-mappings for bounded reconciliation lookups when you already hold provider_mappings:read and the relevant resource read scope. Do not use staff_id as a universal connector id.

Org-unit sync

1. Request org_units:read.
2. Call GET /org-units to build the organisation-structure cache.
3. Treat departments as org units with type: "department".
4. Call GET /people/{personId}/org-links when you need all memberships and reporting relationships for a person.
5. Use provider identity fields on org units where present. Safe org-unit writes can set provider ids for reconciliation. Generic writes for person org-unit memberships and reporting relationships remain read-only.

Employment sync

1. Read People and Employment resources for current job context.
2. Use ETags and If-Match for conditional updates.
3. Send Idempotency-Key on supported public writes.
4. Treat working-pattern/FTE fields as HR context, not payroll certification.

Time-off sync

1. Use /time-off with date filters for absence windows.
2. Use /people/{personId}/time-off-balance for balances.
3. Join /reference/time-off-categories, /time-off/settings, and /public-holidays for policy context.
4. Use webhooks to invalidate a downstream cache after public API-origin writes.

Custom-field sync

1. Fetch definitions with GET /custom-fields.
2. Read or write values with /people/{personId}/custom-fields.
3. Respect field sensitivity and do not use custom fields for payroll, bank, government identifier, or unsupported demographic data.

Payroll readiness export

1. Request payroll_exports:read.
2. Call GET /payroll-readiness-export.
3. Use the people CSV for safe payroll/accounting readiness checks.
4. Use the field manifest and README to decide what a named payroll connector would still need.

This endpoint does not return raw salary, compensation history, bank details, NI/tax/government identifiers, date of birth, home address, payroll runs, payslips, or statutory-pay calculations.

Beta boundaries

The beta API does not currently expose:

• person org-link writes, cost-allocation splits, payroll legal-entity registration, custom org-unit metadata, or org-chart mutation semantics;
• payroll, compensation, bank, tax, or government identifier fields;
• demographics or equality fields;
• document bytes or signed downloads;
• avatar/photo writes or inline avatar bytes;
• SCIM provisioning;
• reports;
• benefits, training, expenses, performance, or project modules.

Those are not hidden in another endpoint. They are future product/API decisions.

Sample test tenant

For a realistic test integration, create a tenant with:

• a few active people, one pending starter, and one leaver;
• at least two org units, including one department and one team or legal entity, plus a manager chain;
• working-pattern/FTE assignments;
• employment history for one or two people;
• time-off categories, one pending request, one approved request, and one balance example;
• one standard custom field and one sensitive custom field;
• a webhook endpoint connected to a test receiver.

Use synthetic people and clearly fake values. Do not use real employee, payroll, bank, government, or document-content data in test integrations.