openapi: 3.1.0
info:
  title: Humaans API
  version: '1.0'
  description: |
    The Humaans HRIS API exposes the People, Compensations, Time Away, Documents,
    Locations, Job Roles, Custom Fields, Performance, Timesheet, Webhooks, and
    related resources of the Humaans system of record. The API is REST-based,
    accepts and returns JSON, and uses Bearer token authentication scoped via
    OAuth scopes (public:read, private:read, private:write, compensations:read,
    compensations:write, documents:read, documents:write, webhooks:manage).
  contact:
    name: Humaans
    url: https://docs.humaans.io/api/
  termsOfService: https://humaans.io/terms
servers:
- url: https://app.humaans.io/api
  description: Humaans API production endpoint
security:
- bearerAuth: []
tags:
- name: People
  description: Employee records, the canonical resource of the HRIS
- name: Companies
  description: Tenant company record
- name: Compensations
  description: Salary, bonus, and compensation history
- name: Bank Accounts
  description: Employee bank account records
- name: Documents
  description: Personal and company document storage
- name: Time Away
  description: Time off, holidays, leave allocations, policies, and types
- name: Equipment
  description: Equipment assigned to employees
- name: Job Roles
  description: Position and role definitions
- name: Locations
  description: Office and remote work locations
- name: Custom Fields
  description: Tenant-defined custom field definitions and values
- name: Performance
  description: Performance reviews, cycles, templates, and ratings
- name: Timesheet
  description: Timesheet entries and submissions
- name: Webhooks
  description: Outbound HMAC-signed event subscriptions
- name: Audit Events
  description: Read-only audit trail
- name: Working Patterns
  description: Work schedule patterns
paths:
  /people:
    get:
      tags: [People]
      summary: List People
      operationId: listPeople
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Skip'
      responses:
        '200':
          description: Paginated list of people
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonList'
    post:
      tags: [People]
      summary: Create Person
      operationId: createPerson
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Person'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
  /people/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      tags: [People]
      summary: Retrieve Person
      operationId: getPerson
      responses:
        '200':
          description: Person record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
    patch:
      tags: [People]
      summary: Update Person
      operationId: updatePerson
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Person'
      responses:
        '200':
          description: Updated person
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
    delete:
      tags: [People]
      summary: Delete Person
      operationId: deletePerson
      responses:
        '204':
          description: Deleted
  /companies:
    get:
      tags: [Companies]
      summary: List Companies
      operationId: listCompanies
      responses:
        '200':
          description: Company list
  /companies/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      tags: [Companies]
      summary: Retrieve Company
      operationId: getCompany
      responses:
        '200':
          description: Company record
    patch:
      tags: [Companies]
      summary: Update Company
      operationId: updateCompany
      responses:
        '200':
          description: Updated company
  /compensations:
    get:
      tags: [Compensations]
      summary: List Compensations
      operationId: listCompensations
      responses:
        '200':
          description: Compensation list
    post:
      tags: [Compensations]
      summary: Create Compensation
      operationId: createCompensation
      responses:
        '201':
          description: Created compensation
  /compensations/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      tags: [Compensations]
      summary: Retrieve Compensation
      operationId: getCompensation
      responses:
        '200':
          description: Compensation record
    patch:
      tags: [Compensations]
      summary: Update Compensation
      operationId: updateCompensation
      responses:
        '200':
          description: Updated compensation
    delete:
      tags: [Compensations]
      summary: Delete Compensation
      operationId: deleteCompensation
      responses:
        '204':
          description: Deleted
  /bank-accounts:
    get:
      tags: [Bank Accounts]
      summary: List Bank Accounts
      operationId: listBankAccounts
      responses:
        '200':
          description: Bank account list
    post:
      tags: [Bank Accounts]
      summary: Create Bank Account
      operationId: createBankAccount
      responses:
        '201':
          description: Created
  /bank-accounts/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      tags: [Bank Accounts]
      summary: Retrieve Bank Account
      operationId: getBankAccount
      responses:
        '200':
          description: Bank account
    patch:
      tags: [Bank Accounts]
      summary: Update Bank Account
      operationId: updateBankAccount
      responses:
        '200':
          description: Updated
    delete:
      tags: [Bank Accounts]
      summary: Delete Bank Account
      operationId: deleteBankAccount
      responses:
        '204':
          description: Deleted
  /documents:
    get:
      tags: [Documents]
      summary: List Documents
      operationId: listDocuments
      responses:
        '200':
          description: Document list
    post:
      tags: [Documents]
      summary: Create Document
      operationId: createDocument
      responses:
        '201':
          description: Created document
  /documents/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      tags: [Documents]
      summary: Retrieve Document
      operationId: getDocument
      responses:
        '200':
          description: Document
    patch:
      tags: [Documents]
      summary: Update Document
      operationId: updateDocument
      responses:
        '200':
          description: Updated
    delete:
      tags: [Documents]
      summary: Delete Document
      operationId: deleteDocument
      responses:
        '204':
          description: Deleted
  /time-away:
    get:
      tags: [Time Away]
      summary: List Time Away
      operationId: listTimeAway
      responses:
        '200':
          description: Time away list
    post:
      tags: [Time Away]
      summary: Create Time Away
      operationId: createTimeAway
      responses:
        '201':
          description: Created
  /time-away/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      tags: [Time Away]
      summary: Retrieve Time Away
      operationId: getTimeAway
      responses:
        '200':
          description: Time away record
    patch:
      tags: [Time Away]
      summary: Update Time Away
      operationId: updateTimeAway
      responses:
        '200':
          description: Updated
    delete:
      tags: [Time Away]
      summary: Delete Time Away
      operationId: deleteTimeAway
      responses:
        '204':
          description: Deleted
  /time-away-types:
    get:
      tags: [Time Away]
      summary: List Time Away Types
      operationId: listTimeAwayTypes
      responses:
        '200':
          description: List
  /time-away-policies:
    get:
      tags: [Time Away]
      summary: List Time Away Policies
      operationId: listTimeAwayPolicies
      responses:
        '200':
          description: List
  /time-away-allocations:
    get:
      tags: [Time Away]
      summary: List Time Away Allocations
      operationId: listTimeAwayAllocations
      responses:
        '200':
          description: List
  /equipment:
    get:
      tags: [Equipment]
      summary: List Equipment
      operationId: listEquipment
      responses:
        '200':
          description: Equipment list
    post:
      tags: [Equipment]
      summary: Create Equipment
      operationId: createEquipment
      responses:
        '201':
          description: Created
  /equipment/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      tags: [Equipment]
      summary: Retrieve Equipment
      operationId: getEquipment
      responses:
        '200':
          description: Equipment
    patch:
      tags: [Equipment]
      summary: Update Equipment
      operationId: updateEquipment
      responses:
        '200':
          description: Updated
    delete:
      tags: [Equipment]
      summary: Delete Equipment
      operationId: deleteEquipment
      responses:
        '204':
          description: Deleted
  /job-roles:
    get:
      tags: [Job Roles]
      summary: List Job Roles
      operationId: listJobRoles
      responses:
        '200':
          description: List
    post:
      tags: [Job Roles]
      summary: Create Job Role
      operationId: createJobRole
      responses:
        '201':
          description: Created
  /job-roles/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      tags: [Job Roles]
      summary: Retrieve Job Role
      operationId: getJobRole
      responses:
        '200':
          description: Job role
    patch:
      tags: [Job Roles]
      summary: Update Job Role
      operationId: updateJobRole
      responses:
        '200':
          description: Updated
    delete:
      tags: [Job Roles]
      summary: Delete Job Role
      operationId: deleteJobRole
      responses:
        '204':
          description: Deleted
  /locations:
    get:
      tags: [Locations]
      summary: List Locations
      operationId: listLocations
      responses:
        '200':
          description: Location list
    post:
      tags: [Locations]
      summary: Create Location
      operationId: createLocation
      responses:
        '201':
          description: Created
  /locations/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      tags: [Locations]
      summary: Retrieve Location
      operationId: getLocation
      responses:
        '200':
          description: Location
    patch:
      tags: [Locations]
      summary: Update Location
      operationId: updateLocation
      responses:
        '200':
          description: Updated
    delete:
      tags: [Locations]
      summary: Delete Location
      operationId: deleteLocation
      responses:
        '204':
          description: Deleted
  /custom-fields:
    get:
      tags: [Custom Fields]
      summary: List Custom Fields
      operationId: listCustomFields
      responses:
        '200':
          description: List
    post:
      tags: [Custom Fields]
      summary: Create Custom Field
      operationId: createCustomField
      responses:
        '201':
          description: Created
  /custom-values:
    get:
      tags: [Custom Fields]
      summary: List Custom Values
      operationId: listCustomValues
      responses:
        '200':
          description: List
    post:
      tags: [Custom Fields]
      summary: Create Custom Value
      operationId: createCustomValue
      responses:
        '201':
          description: Created
  /performance-reviews:
    get:
      tags: [Performance]
      summary: List Performance Reviews
      operationId: listPerformanceReviews
      responses:
        '200':
          description: List
  /performance-cycles:
    get:
      tags: [Performance]
      summary: List Performance Cycles
      operationId: listPerformanceCycles
      responses:
        '200':
          description: List
  /performance-templates:
    get:
      tags: [Performance]
      summary: List Performance Templates
      operationId: listPerformanceTemplates
      responses:
        '200':
          description: List
  /timesheet-entries:
    get:
      tags: [Timesheet]
      summary: List Timesheet Entries
      operationId: listTimesheetEntries
      responses:
        '200':
          description: List
    post:
      tags: [Timesheet]
      summary: Create Timesheet Entry
      operationId: createTimesheetEntry
      responses:
        '201':
          description: Created
  /timesheet-submissions:
    get:
      tags: [Timesheet]
      summary: List Timesheet Submissions
      operationId: listTimesheetSubmissions
      responses:
        '200':
          description: List
  /webhooks:
    get:
      tags: [Webhooks]
      summary: List Webhooks
      operationId: listWebhooks
      responses:
        '200':
          description: List
    post:
      tags: [Webhooks]
      summary: Create Webhook
      operationId: createWebhook
      responses:
        '201':
          description: Created
  /webhooks/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      tags: [Webhooks]
      summary: Retrieve Webhook
      operationId: getWebhook
      responses:
        '200':
          description: Webhook
    patch:
      tags: [Webhooks]
      summary: Update Webhook
      operationId: updateWebhook
      responses:
        '200':
          description: Updated
    delete:
      tags: [Webhooks]
      summary: Delete Webhook
      operationId: deleteWebhook
      responses:
        '204':
          description: Deleted
  /audit-events:
    get:
      tags: [Audit Events]
      summary: List Audit Events
      operationId: listAuditEvents
      responses:
        '200':
          description: Audit event list
  /working-patterns:
    get:
      tags: [Working Patterns]
      summary: List Working Patterns
      operationId: listWorkingPatterns
      responses:
        '200':
          description: Working pattern list
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: Bearer access token issued by Humaans with OAuth-style scopes
  parameters:
    Id:
      name: id
      in: path
      required: true
      schema:
        type: string
    Limit:
      name: $limit
      in: query
      required: false
      description: Maximum results per page (default 100, max 250)
      schema:
        type: integer
        default: 100
        maximum: 250
    Skip:
      name: $skip
      in: query
      required: false
      description: Number of results to skip for pagination
      schema:
        type: integer
        default: 0
  schemas:
    Person:
      type: object
      properties:
        id:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        personalEmail:
          type: string
          format: email
        phoneNumber:
          type: string
        jobTitle:
          type: string
        jobRoleId:
          type: string
        locationId:
          type: string
        companyId:
          type: string
        managerId:
          type: string
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        employmentType:
          type: string
        status:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PersonList:
      type: object
      properties:
        total:
          type: integer
        limit:
          type: integer
        skip:
          type: integer
        data:
          type: array
          items:
            $ref: '#/components/schemas/Person'