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, public API-origin write events, and the in-app domain-event paths already wired through the event spine.
Integration readiness	Aggregate readiness for payroll, spend, and accounting handoffs, including people lifecycle, leaver-date safety, org-structure coverage, and webhook health.

Integration readiness

Use GET /integration-readiness before wiring a payroll, spend, accounting, or low-code sync. It returns a versioned readiness contract for:

• people_lifecycle: active people, missing start dates, archived members without employment end dates, and active people whose end date has passed;
• org_structure: active departments, teams, divisions, cost centres, legal entities, location groups, and primary department/cost-centre coverage;
• webhooks: active webhook endpoint counts, person.ended coverage, org-unit event coverage, and endpoint health when the API key has webhooks:manage;
• provider playbooks for xero_payroll_uk, xero_expenses, freeagent, dext, pleo, and soldo.

The endpoint requires people:read. If the same API key also has webhooks:manage, the response includes safe webhook endpoint inventory and health. Without webhooks:manage, webhook readiness is marked as not fully visible and no endpoint names or ids are returned.

The response is deliberately aggregate-first. It does not return salary, bank details, date of birth, home address, government identifiers, receipt images, expense line items, payroll-run data, provider credentials, or webhook signing secrets. native_connector is false for every provider in v1.

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 covered public API-origin or in-app domain-event 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.

Expense and spend tools

1. Call GET /integration-readiness and fix blockers before creating a sync.
2. Keep claims, receipts, cards, reimbursements, VAT, ledger posting, and bank reconciliation in the specialist finance/spend tool.
3. Use people:read, org_units:read, provider_mappings:read, and webhooks:manage for the HollyHR side of a user/cost-centre sync.
4. Map departments, cost centres, and legal entities from canonical org units.
5. Use updated_since polling plus webhooks for joiner/mover/leaver sync; do not rely on a single event delivery for card-disable automation.
6. Follow Expense and spend tools for provider-specific positioning across Xero Expenses, FreeAgent, Dext, Pleo, Soldo, Expensify, and Zoho Expense.

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, native expense claims/cards, 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.