HollyHR Provider Mappings API

openapi: 3.2.0
info:
  title: HollyHR API Reference Provider Mappings 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: Provider Mappings
  description: Active external/provider ID reconciliation metadata. Requires provider_mappings:read plus the relevant resource read scope.
paths:
  /provider-mappings:
    get:
      operationId: listProviderMappings
      tags:
      - Provider Mappings
      summary: List active provider mappings
      description: 'Lists active external/provider ID mappings for a bounded local resource lookup. The request must include provider_name, resource_type, and resource_id. remote_object_type plus external_id can be supplied as an additional narrowing filter. This endpoint returns reconciliation metadata only: no raw mapped resource payload, no provider metadata, no API-key provenance, and no deleted mapping history. Keys require provider_mappings:read plus the relevant resource read scope before any lookup runs.'
      security:
      - ApiKeyAuth: []
      x-required-scope: provider_mappings:read
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
        required: false
        name: limit
        in: query
      - schema:
          type: string
          minLength: 1
        required: false
        name: cursor
        in: query
      - schema:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[a-z0-9][a-z0-9._:-]*$
        required: true
        name: provider_name
        in: query
      - schema:
          type: string
          minLength: 1
          maxLength: 128
          pattern: ^[a-zA-Z0-9._:-]+$
          default: default
        required: false
        name: provider_account_id
        in: query
      - schema:
          type: string
          enum:
          - person
          - org_unit
          - person_org_unit_membership
          - person_relationship
          - custom_field_definition
          - time_off
          - working_pattern
        required: true
        name: resource_type
        in: query
      - schema:
          type: string
          minLength: 1
        required: false
        name: resource_id
        in: query
      - schema:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[a-z0-9][a-z0-9._:-]*$
        required: false
        name: remote_object_type
        in: query
      - schema:
          type: string
          minLength: 1
          maxLength: 255
        required: false
        name: external_id
        in: query
      responses:
        '200':
          description: A cursor page of active provider mappings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderMappingList'
        '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:
      - integrations.provider-mappings.view
components:
  schemas:
    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
    ProviderMappingList:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              provider_name:
                type: string
              provider_account_id:
                type: string
              remote_object_type:
                type: string
              external_id:
                type: string
              remote_id:
                type:
                - string
                - 'null'
              resource_type:
                type: string
                enum:
                - person
                - org_unit
                - person_org_unit_membership
                - person_relationship
                - custom_field_definition
                - time_off
                - working_pattern
              resource_id:
                anyOf:
                - type: string
                  pattern: ^[0123456789abcdefghjkmnpqrstvwxyz]{12}$
                - type: string
                  pattern: ^org_unit_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
                - type: string
                  pattern: ^org_unit_membership_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
                - type: string
                  pattern: ^person_relationship_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
                - type: string
                  pattern: ^cfd_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
                - type: string
                  pattern: ^time_off_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
                - type: string
                  pattern: ^working_pattern_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
              sync_status:
                type: string
                enum:
                - linked
                - pending
                - conflict
              created_at:
                type: string
                format: date-time
              updated_at:
                type: string
                format: date-time
            required:
            - provider_name
            - provider_account_id
            - remote_object_type
            - external_id
            - remote_id
            - resource_type
            - resource_id
            - sync_status
            - created_at
            - updated_at
            additionalProperties: false
        pagination:
          type: object
          properties:
            next_cursor:
              type:
              - string
              - 'null'
            has_more:
              type: boolean
            limit:
              type: integer
              minimum: 1
              maximum: 100
          required:
          - next_cursor
          - has_more
          - limit
          additionalProperties: false
      required:
      - data
      - pagination
      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)