# 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](/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.