Copy page

Core API

Fields and Metadata

Use this guide when an integration needs to understand which fields exist, which scopes expose them, why a field is absent, or how to resolve ids into human-readable labels.

Field discovery sources

Source	Use it for	What it does not do
OpenAPI schema	Exact request/response schemas, error envelopes, headers, parameters, and examples.	It does not describe tenant-specific custom-field definitions.
GET /metadata	Machine-readable route, scope, parameter, schema-field, field-category, and webhook-event requirements generated from the public contract.	It does not expose tenant data, custom-field values, or hidden product fields.
GET /custom-fields	API-visible person custom-field definitions configured by the tenant.	It cannot create or edit definitions. Hidden definitions are omitted.
Reference endpoints	Stable ids and display labels for dictionaries such as countries, people statuses, work types, work places, time-off statuses, time-off categories, and document types.	They are not a generic named-list or custom-table system.
Module guides	Product-domain field posture, common workflows, and beta limits.	They do not replace the generated endpoint contract.

Sensitive and elevated fields

Default People responses intentionally omit personal contact data, home addresses, date of birth, demographics, compensation, bank details, tax or government identifiers, avatar bytes, document bytes, and free-text sensitive notes.

Some safe elevated reads are available only through separate detail endpoints and scopes:

• GET /people/{personId}/personal requires people:personal:read.
• GET /people/{personId}/avatar requires people:avatar:read.
• GET /documents and GET /documents/{documentId} require documents:read and return metadata only.
• GET /payroll-readiness-export requires payroll_exports:read and returns readiness data and presence signals, not raw payroll, bank, tax, NI, or compensation values.

If a field is not in one of those surfaces, treat that as an explicit product boundary, not a discoverability problem.

Custom fields

Person custom-field definitions are managed in HollyHR under Settings > Custom Fields. Admins decide whether each definition is hidden from the API, read-only through the API, or read/write through the API.

An API key needs:

• custom_fields:read for GET /custom-fields and GET /people/{personId}/custom-fields;
• custom_fields:write for PATCH /people/{personId}/custom-fields.

Single-select values use the configured option value, not the display label. Store stable ids or configured values in integrations, and refresh display labels from HollyHR when rendering user-facing views.

Resolving ids and labels

HollyHR prefers stable ids and structured objects over display-label matching. Use reference endpoints for standard dictionaries:

• /reference/countries
• /reference/statuses
• /reference/work-types
• /reference/work-places
• /reference/time-off-statuses
• /reference/time-off-categories
• /reference/document-types

GET /metadata tells an integration which fields and scopes exist in the public contract. Reference endpoints and resource payloads provide tenant or dictionary labels. There is no generic HiBob-style named-list/table creation API in the current beta.

Troubleshooting missing fields

Symptom	Likely cause	What to check
403 permission_denied	The key lacks the required scope.	Check the endpoint guide, GET /metadata, and the key's scope list in GET /me.
Field missing from GET /people	The field is elevated, unsupported, or intentionally excluded from the base projection.	Check the People field posture and the personal/avatar detail endpoints.
Custom-field definition missing	The definition is hidden from the API or is not a person custom field.	Check Settings > Custom Fields and the definition's API access setting.
Custom-field value cannot be updated	The field is not writable or the key lacks custom_fields:write.	Fetch definitions and current values, then retry with If-Match and Idempotency-Key.
Document lacks a download URL	Document bytes and signed URLs are outside the beta API.	Use document metadata only, or track the document-byte API as future product work.
Webhook payload lacks full resource data	Webhook events are intentionally compact.	Fetch current state through the REST endpoint with the matching read scope.
Payroll or compensation field absent	Payroll/compensation/bank/tax data is not exposed by public API scopes.	Use the payroll-readiness export only for readiness and gap signals.
404 not_found for a resource that exists in HollyHR	The id may be malformed, cross-tenant, deleted, or not exposed through the beta module.	Re-read from the list endpoint using the same key and scope set.

Integration rule

Do not infer sensitive fields from UI labels, undocumented response keys, or internal product names. Use OpenAPI for contract shape, GET /metadata for machine-readable discovery, reference endpoints for stable dictionaries, and module guides for the privacy and beta boundaries behind each field family.