HollyHR Organisation API

openapi: 3.2.0
info:
  title: HollyHR API Reference Organisation 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: Organisation
  description: Safe company profile and active location reads.
paths:
  /organisation:
    get:
      operationId: getOrganisation
      tags:
      - Organisation
      summary: Fetch organisation account details
      description: Fetches safe company/account details for the authenticated organisation. The projection excludes owner user ids, created/updated user ids, custom-domain provider configuration, verification payloads, and other internal tenant infrastructure fields.
      security:
      - ApiKeyAuth: []
      x-required-scope: organisation:read
      responses:
        '200':
          description: Safe organisation account projection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganisationResponse'
        '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'
        '404':
          description: Organisation not found.
          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.organisation.manage
  /organisation/locations:
    get:
      operationId: listOrganisationLocations
      tags:
      - Organisation
      summary: List active organisation locations
      description: Lists active work locations for the authenticated organisation. Locations are organisation-owned office/worksite records, not employee home addresses.
      security:
      - ApiKeyAuth: []
      x-required-scope: organisation:read
      responses:
        '200':
          description: Active organisation locations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganisationLocationList'
        '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.workplace.manage
components:
  schemas:
    OrganisationLocationList:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                pattern: ^loc_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
              label:
                type: string
              address_line_1:
                type: string
              address_line_2:
                type:
                - string
                - 'null'
              address_line_3:
                type:
                - string
                - 'null'
              city:
                type: string
              region_state:
                type: string
              postal_code:
                type: string
              country:
                type: object
                properties:
                  id:
                    type: string
                    pattern: ^cty_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
                  name:
                    type: string
                  country_code:
                    type: string
                  geography:
                    type: object
                    properties:
                      country_code:
                        type: string
                        minLength: 2
                        maxLength: 2
                      country_name:
                        type: string
                      subdivision_code:
                        type:
                        - string
                        - 'null'
                      subdivision_name:
                        type:
                        - string
                        - 'null'
                    required:
                    - country_code
                    - country_name
                    - subdivision_code
                    - subdivision_name
                    additionalProperties: false
                required:
                - id
                - name
                - country_code
                additionalProperties: false
              capacity:
                type:
                - integer
                - 'null'
              is_active:
                type: boolean
              created_at:
                type: string
                format: date-time
              updated_at:
                type: string
                format: date-time
            required:
            - id
            - label
            - address_line_1
            - address_line_2
            - address_line_3
            - city
            - region_state
            - postal_code
            - country
            - capacity
            - is_active
            - created_at
            - updated_at
            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
    OrganisationResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              pattern: ^org_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
            name:
              type:
              - string
              - 'null'
            subdomain:
              type:
              - string
              - 'null'
            country:
              type:
              - object
              - 'null'
              properties:
                id:
                  type: string
                  pattern: ^cty_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
                name:
                  type: string
                country_code:
                  type: string
                geography:
                  type: object
                  properties:
                    country_code:
                      type: string
                      minLength: 2
                      maxLength: 2
                    country_name:
                      type: string
                    subdivision_code:
                      type:
                      - string
                      - 'null'
                    subdivision_name:
                      type:
                      - string
                      - 'null'
                  required:
                  - country_code
                  - country_name
                  - subdivision_code
                  - subdivision_name
                  additionalProperties: false
              required:
              - id
              - name
              - country_code
              additionalProperties: false
            plan:
              type: string
            logo_url:
              type:
              - string
              - 'null'
            primary_color_light:
              type:
              - string
              - 'null'
            primary_color_dark:
              type:
              - string
              - 'null'
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
          required:
          - id
          - name
          - subdomain
          - country
          - plan
          - logo_url
          - primary_color_light
          - primary_color_dark
          - created_at
          - updated_at
          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)