HollyHR Integrations API

openapi: 3.2.0
info:
  title: HollyHR API Reference Integrations 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: Integrations
paths:
  /integration-readiness:
    get:
      operationId: getIntegrationReadiness
      tags:
      - Integrations
      summary: Inspect integration readiness
      description: Returns aggregate readiness for using HollyHR as the people, org-structure, lifecycle, and webhook source of truth for payroll, spend, and accounting handoffs. The response is a readiness/playbook contract, not evidence of native first-party connectors. It never returns raw salary, bank, DOB, home-address, receipt, expense, payroll-run, or provider-secret values. Keys require people:read; webhook endpoint inventory is included only when the same key also has webhooks:manage.
      security:
      - ApiKeyAuth: []
      x-required-scope: people:read
      responses:
        '200':
          description: Integration readiness summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationReadinessResponse'
        '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:
      - settings.integrations.view
components:
  schemas:
    IntegrationReadinessResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            contract_version:
              type: string
              enum:
              - 2026-07-07.integration-control-plane.v1
            generated_at:
              type: string
              format: date-time
            status:
              type: string
              enum:
              - ready
              - needs_attention
              - not_configured
            domains:
              type: object
              properties:
                people_lifecycle:
                  type: object
                  properties:
                    status:
                      type: string
                      enum:
                      - ready
                      - needs_attention
                      - not_configured
                    issues:
                      type: array
                      items:
                        type: object
                        properties:
                          code:
                            type: string
                          severity:
                            type: string
                            enum:
                            - blocker
                            - warning
                            - info
                          domain:
                            type: string
                            enum:
                            - people_lifecycle
                            - org_structure
                            - webhooks
                          message:
                            type: string
                          action:
                            type: string
                        required:
                        - code
                        - severity
                        - domain
                        - message
                        - action
                        additionalProperties: false
                    metrics:
                      type: object
                      properties:
                        active_people:
                          type: integer
                          minimum: 0
                        active_missing_start_date:
                          type: integer
                          minimum: 0
                        archived_without_end_date:
                          type: integer
                          minimum: 0
                        active_with_past_end_date:
                          type: integer
                          minimum: 0
                      required:
                      - active_people
                      - active_missing_start_date
                      - archived_without_end_date
                      - active_with_past_end_date
                      additionalProperties: false
                  required:
                  - status
                  - issues
                  - metrics
                  additionalProperties: false
                org_structure:
                  type: object
                  properties:
                    status:
                      type: string
                      enum:
                      - ready
                      - needs_attention
                      - not_configured
                    issues:
                      type: array
                      items:
                        type: object
                        properties:
                          code:
                            type: string
                          severity:
                            type: string
                            enum:
                            - blocker
                            - warning
                            - info
                          domain:
                            type: string
                            enum:
                            - people_lifecycle
                            - org_structure
                            - webhooks
                          message:
                            type: string
                          action:
                            type: string
                        required:
                        - code
                        - severity
                        - domain
                        - message
                        - action
                        additionalProperties: false
                    metrics:
                      type: object
                      properties:
                        active_units:
                          type: object
                          properties:
                            department:
                              type: integer
                              minimum: 0
                            team:
                              type: integer
                              minimum: 0
                            division:
                              type: integer
                              minimum: 0
                            cost_centre:
                              type: integer
                              minimum: 0
                            legal_entity:
                              type: integer
                              minimum: 0
                            location_group:
                              type: integer
                              minimum: 0
                          required:
                          - department
                          - team
                          - division
                          - cost_centre
                          - legal_entity
                          - location_group
                          additionalProperties: false
                        active_people_missing_primary_department:
                          type: integer
                          minimum: 0
                        active_people_missing_primary_cost_centre:
                          type: integer
                          minimum: 0
                      required:
                      - active_units
                      - active_people_missing_primary_department
                      - active_people_missing_primary_cost_centre
                      additionalProperties: false
                  required:
                  - status
                  - issues
                  - metrics
                  additionalProperties: false
                webhooks:
                  type: object
                  properties:
                    status:
                      type: string
                      enum:
                      - ready
                      - needs_attention
                      - not_configured
                    issues:
                      type: array
                      items:
                        type: object
                        properties:
                          code:
                            type: string
                          severity:
                            type: string
                            enum:
                            - blocker
                            - warning
                            - info
                          domain:
                            type: string
                            enum:
                            - people_lifecycle
                            - org_structure
                            - webhooks
                          message:
                            type: string
                          action:
                            type: string
                        required:
                        - code
                        - severity
                        - domain
                        - message
                        - action
                        additionalProperties: false
                    metrics:
                      type: object
                      properties:
                        visible:
                          type: boolean
                        active_endpoints:
                          type: integer
                          minimum: 0
                        endpoints_with_person_ended:
                          type: integer
                          minimum: 0
                        endpoints_with_org_unit_events:
                          type: integer
                          minimum: 0
                        failing_endpoints:
                          type: integer
                          minimum: 0
                        endpoints:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                pattern: ^wh_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
                              name:
                                type: string
                              status:
                                type: string
                                enum:
                                - active
                                - disabled
                              health_status:
                                type: string
                                enum:
                                - healthy
                                - recovering
                                - failing
                                - inactive
                                - unknown
                              subscribed_events:
                                type: array
                                items:
                                  type: string
                                  enum:
                                  - person.created
                                  - person.updated
                                  - person.ended
                                  - person.reactivated
                                  - time_off.created
                                  - time_off.updated
                                  - time_off.approved
                                  - time_off.declined
                                  - time_off.cancelled
                                  - time_off_category.created
                                  - time_off_category.updated
                                  - time_off_category.archived
                                  - time_off_settings.updated
                                  - org_unit.created
                                  - org_unit.updated
                                  - org_unit.archived
                                  - org_unit.reactivated
                                  - working_pattern.created
                                  - working_pattern.updated
                                  - working_pattern.archived
                                  - webhook.test
                              action_required:
                                type: boolean
                              recommended_action:
                                type: string
                                enum:
                                - none
                                - inspect_failures
                                - wait_for_retry
                                - enable_endpoint
                              last_success_at:
                                type:
                                - string
                                - 'null'
                                format: date-time
                              last_failure_at:
                                type:
                                - string
                                - 'null'
                                format: date-time
                            required:
                            - id
                            - name
                            - status
                            - health_status
                            - subscribed_events
                            - action_required
                            - recommended_action
                            - last_success_at
                            - last_failure_at
                            additionalProperties: false
                      required:
                      - visible
                      - active_endpoints
                      - endpoints_with_person_ended
                      - endpoints_with_org_unit_events
                      - failing_endpoints
                      - endpoints
                      additionalProperties: false
                  required:
                  - status
                  - issues
                  - metrics
                  additionalProperties: false
              required:
              - people_lifecycle
              - org_structure
              - webhooks
              additionalProperties: false
            providers:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    enum:
                    - xero_payroll_uk
                    - xero_expenses
                    - freeagent
                    - dext
                    - pleo
                    - soldo
                  name:
                    type: string
                  category:
                    type: string
                    enum:
                    - payroll
                    - spend
                    - accounting
                  status:
                    type: string
                    enum:
                    - ready
                    - needs_attention
                    - not_configured
                  native_connector:
                    type: boolean
                    enum:
                    - false
                  summary:
                    type: string
                  required_domains:
                    type: array
                    items:
                      type: string
                      enum:
                      - people_lifecycle
                      - org_structure
                      - webhooks
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        severity:
                          type: string
                          enum:
                          - blocker
                          - warning
                          - info
                        domain:
                          type: string
                          enum:
                          - people_lifecycle
                          - org_structure
                          - webhooks
                        message:
                          type: string
                        action:
                          type: string
                      required:
                      - code
                      - severity
                      - domain
                      - message
                      - action
                      additionalProperties: false
                  docs_href:
                    type: string
                required:
                - id
                - name
                - category
                - status
                - native_connector
                - summary
                - required_domains
                - issues
                - docs_href
                additionalProperties: false
          required:
          - contract_version
          - generated_at
          - status
          - domains
          - providers
          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
  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)