HollyHR Exports API

openapi: 3.2.0
info:
  title: HollyHR API Reference Exports API
  version: 1.0.0-foundation
  description: Governed Public Preview API with organisation-scoped reads and bounded signed-webhook management available on every plan, and governed programmatic writes included on Standard and above through explicitly selected scopes. This version covers API-key context, people directory sync, safe people setup, conditional setup-field updates, safe lifecycle actions, safe employment writes, canonical org-unit reads and person org links, working-pattern reads and writes, safe time-off writes, time-off sync, public holidays, document metadata sync, reference data, and outbound webhook management. Responses use explicit deny-by-default projections and opaque public ids; person ids are stored random tenant-person identifiers while other resource ids remain encrypted. orgId is always resolved from the bearer key and is never accepted from request input.
servers:
- url: /api/v1
  description: Public API path on the current HollyHR app origin.
- url: https://sandbox.hollyhr.com/api/v1
  description: Seeded HollyHR sandbox tenant for hhr_test_ API keys.
security:
- ApiKeyAuth: []
tags:
- name: Exports
  description: Safe export packages for operational handoff. Native payroll/accounting connectors and raw payroll-sensitive values are not exposed.
paths:
  /payroll-readiness-export:
    get:
      operationId: getPayrollReadinessExport
      tags:
      - Exports
      summary: Download the payroll readiness export
      description: Returns the versioned HollyHR payroll readiness export package as JSON file payloads. This is a provider-neutral handoff for payroll review and bureau/accountant workflows, not a native payroll connector. The package includes safe operational identity, employment, organisation, working-time fields, and sensitive-field presence flags only. By default it never exports raw DOB, home address, compensation, bank, tax/government identifiers, payroll run data, or payslips. When the organisation has an active ADR-0009 payroll-financial export grant WITH its allow-API-exports toggle enabled, the granted value tiers (personal_setup and/or payroll_financial) are included as additional CSV columns; bank details are never included under any grant. The optional provider preset (currently xero_payroll_uk) adds provider-shaped upload-template and readiness files for that provider's employee-import workflow without widening the exported data. Existing workspaces keep version one until employer setup is activated. Activated workspaces must select employer_id and receive version two employer-specific files; unknown dated facts block a complete handoff. gap_report=true returns a clearly incomplete report without provider files or sensitive granted values.
      security:
      - ApiKeyAuth: []
      x-required-scope: payroll_exports:read
      parameters:
      - schema:
          type: string
          enum:
          - xero_payroll_uk
        required: false
        name: provider
        in: query
      - schema:
          type: string
          maxLength: 1024
          pattern: ^employer_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
        required: false
        name: employer_id
        in: query
      - schema:
          type: string
          enum:
          - 'true'
          - 'false'
        required: false
        name: gap_report
        in: query
      responses:
        '200':
          description: A safe payroll readiness export package.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayrollReadinessExportResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing, malformed, unknown, revoked, or expired API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Missing scope or plan entitlement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. Responses include Retry-After and rate-limit metadata where available.
          headers:
            Retry-After:
              schema:
                type: string
              description: Seconds to wait before retrying the request.
            RateLimit-Limit:
              schema:
                type: string
              description: Current route bucket limit.
            RateLimit-Remaining:
              schema:
                type: string
              description: Requests remaining in the current route bucket window.
            RateLimit-Reset:
              schema:
                type: string
              description: Seconds until the current route bucket resets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      x-hollyhr-domain-capabilities:
      - payroll.readiness.export
  /payroll-changes-export:
    get:
      operationId: getPayrollChangesExport
      tags:
      - Exports
      summary: Download the pay-period payroll changes export
      description: 'Returns starters, leavers, employment changes, and compensation/bank change flags for an inclusive pay-period date range (from/to, YYYY-MM-DD, max 400 days). This is the changes-only companion to the payroll readiness export: it tells a payroll operator, accountant, or bureau what to update without re-keying the whole employee list. By default sensitive payroll values are not included — compensation and bank changes are flags with effective dates only. When the organisation has an active ADR-0009 grant with API exports enabled, granted value tiers appear as additional columns in the starters/leavers files; per-change historical amounts and bank details are never included. Activated employer-aware workspaces must select employer_id. Version two files partition dated employment and historical corrections by employer; unresolved facts or in-period transfers block a complete handoff. gap_report=true returns an incomplete report for manual review.'
      security:
      - ApiKeyAuth: []
      x-required-scope: payroll_exports:read
      parameters:
      - schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
        required: true
        name: from
        in: query
      - schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
        required: true
        name: to
        in: query
      - schema:
          type: string
          maxLength: 1024
          pattern: ^employer_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
        required: false
        name: employer_id
        in: query
      - schema:
          type: string
          enum:
          - 'true'
          - 'false'
        required: false
        name: gap_report
        in: query
      responses:
        '200':
          description: A safe pay-period payroll changes export package.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayrollChangesExportResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing, malformed, unknown, revoked, or expired API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Missing scope or plan entitlement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. Responses include Retry-After and rate-limit metadata where available.
          headers:
            Retry-After:
              schema:
                type: string
              description: Seconds to wait before retrying the request.
            RateLimit-Limit:
              schema:
                type: string
              description: Current route bucket limit.
            RateLimit-Remaining:
              schema:
                type: string
              description: Requests remaining in the current route bucket window.
            RateLimit-Reset:
              schema:
                type: string
              description: Seconds until the current route bucket resets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      x-hollyhr-domain-capabilities:
      - payroll.changes.export
components:
  schemas:
    PayrollReadinessExportResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            format:
              type: string
              enum:
              - hollyhr-payroll-readiness-export
            version:
              type: number
              enum:
              - 1
              - 2
            provider:
              type:
              - string
              - 'null'
              enum:
              - xero_payroll_uk
              - null
            generated_at:
              type: string
              format: date-time
            files:
              type: array
              items:
                type: object
                properties:
                  filename:
                    type: string
                    minLength: 1
                  content:
                    type: string
                required:
                - filename
                - content
                additionalProperties: false
              minItems: 1
          required:
          - format
          - version
          - provider
          - generated_at
          - files
          additionalProperties: false
      required:
      - data
      additionalProperties: false
    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - invalid_request
              - authentication_required
              - permission_denied
              - not_found
              - rate_limited
              - idempotency_required
              - idempotency_conflict
              - conflict
              - precondition_required
              - precondition_failed
              - internal_error
            message:
              type: string
            request_id:
              type: string
              pattern: ^[a-zA-Z0-9._:-]{8,64}$
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  issue:
                    type: string
                required:
                - field
                - issue
                additionalProperties: false
          required:
          - code
          - message
          - request_id
          additionalProperties: false
      required:
      - error
      additionalProperties: false
    PayrollChangesExportResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            format:
              type: string
              enum:
              - hollyhr-payroll-changes-export
            version:
              type: number
              enum:
              - 1
              - 2
            period:
              type: object
              properties:
                fromDate:
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}$
                toDate:
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}$
              required:
              - fromDate
              - toDate
              additionalProperties: false
            generated_at:
              type: string
              format: date-time
            files:
              type: array
              items:
                type: object
                properties:
                  filename:
                    type: string
                    minLength: 1
                  content:
                    type: string
                required:
                - filename
                - content
                additionalProperties: false
              minItems: 1
          required:
          - format
          - version
          - period
          - generated_at
          - files
          additionalProperties: false
      required:
      - data
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: HollyHR API-key bearer token. Each credential is attached to one stable organisation-bound programmatic principal, so rotation does not change the actor or its audit identity. Effective access remains the intersection of the key scopes, current principal grant, plan entitlement and runtime controls.
x-provenance:
  method: harvested
  publisher: HollyHR
  source: https://developers.hollyhr.com/openapi.v1.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)