openapi: 3.1.0
info:
  title: BambooHR REST API
  version: v1
  description: |
    RESTful HTTPS API for the BambooHR HRIS. Access employee data, the employee
    directory, time-off, reports, and files. Authentication is per-customer API
    key (HTTP Basic; username = API key, password = any non-empty string) or
    OAuth 2.0 (bearer token).

    The base URL is per-customer: `https://api.bamboohr.com/api/gateway.php/{companyDomain}/v1`.
  contact:
    name: BambooHR API
    url: https://documentation.bamboohr.com/docs
servers:
  - url: https://api.bamboohr.com/api/gateway.php/{companyDomain}/v1
    description: BambooHR customer endpoint
    variables:
      companyDomain:
        default: mycompany
        description: Your BambooHR subdomain
tags:
  - name: Employees
    description: Employee records
  - name: Directory
    description: Employee directory
  - name: Time Off
    description: Time-off requests and balances
  - name: Reports
    description: Custom and standard reports
  - name: Files
    description: Employee files
  - name: Meta
    description: Field metadata
paths:
  /employees/directory:
    get:
      summary: Get the employee directory
      operationId: getEmployeeDirectory
      tags: [Directory]
      responses:
        '200':
          description: Directory listing
          content:
            application/json:
              schema:
                type: object
                properties:
                  fields:
                    type: array
                    items: { type: object }
                  employees:
                    type: array
                    items: { $ref: '#/components/schemas/Employee' }
      security: [{ basicAuth: [] }, { oauth2: [] }]
  /employees/{id}:
    parameters:
      - { in: path, name: id, required: true, schema: { type: string } }
    get:
      summary: Get an employee
      operationId: getEmployee
      tags: [Employees]
      parameters:
        - { in: query, name: fields, required: true, schema: { type: string }, description: Comma-separated list of fields to return }
      responses:
        '200':
          description: Employee
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Employee' }
      security: [{ basicAuth: [] }, { oauth2: [] }]
    post:
      summary: Update an employee
      operationId: updateEmployee
      tags: [Employees]
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        '200': { description: Updated }
      security: [{ basicAuth: [] }, { oauth2: [] }]
  /employees:
    post:
      summary: Add an employee
      operationId: addEmployee
      tags: [Employees]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [firstName, lastName]
              properties:
                firstName: { type: string }
                lastName: { type: string }
                workEmail: { type: string }
      responses:
        '201':
          description: Created. The Location header contains the new employee URL.
      security: [{ basicAuth: [] }, { oauth2: [] }]
  /employees/{id}/tables/{table}:
    parameters:
      - { in: path, name: id, required: true, schema: { type: string } }
      - { in: path, name: table, required: true, schema: { type: string }, description: Table name (e.g. jobInfo, compensation, employmentStatus) }
    get:
      summary: Get rows from a tabular field for an employee
      operationId: getEmployeeTable
      tags: [Employees]
      responses:
        '200':
          description: Table rows
          content:
            application/json:
              schema:
                type: array
                items: { type: object }
      security: [{ basicAuth: [] }, { oauth2: [] }]
    post:
      summary: Add a row to a tabular field
      operationId: addEmployeeTableRow
      tags: [Employees]
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        '200': { description: Row added }
      security: [{ basicAuth: [] }, { oauth2: [] }]
  /employees/{id}/files/view:
    parameters:
      - { in: path, name: id, required: true, schema: { type: string } }
    get:
      summary: List files for an employee
      operationId: listEmployeeFiles
      tags: [Files]
      responses:
        '200':
          description: Files
          content:
            application/json:
              schema: { type: object }
      security: [{ basicAuth: [] }, { oauth2: [] }]
  /employees/{employeeId}/files/{fileId}:
    parameters:
      - { in: path, name: employeeId, required: true, schema: { type: string } }
      - { in: path, name: fileId, required: true, schema: { type: string } }
    get:
      summary: Get an employee file
      operationId: getEmployeeFile
      tags: [Files]
      responses:
        '200':
          description: File bytes
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
      security: [{ basicAuth: [] }, { oauth2: [] }]
  /reports/{reportId}:
    parameters:
      - { in: path, name: reportId, required: true, schema: { type: string } }
      - { in: query, name: format, schema: { type: string, enum: [JSON, CSV, PDF, XLS, XML] } }
      - { in: query, name: fd, schema: { type: string, enum: ['yes', 'no'] }, description: Filter duplicates }
    get:
      summary: Run a saved report
      operationId: runReport
      tags: [Reports]
      responses:
        '200':
          description: Report data
          content:
            application/json:
              schema: { type: object }
            text/csv:
              schema: { type: string }
            application/pdf:
              schema: { type: string, format: binary }
      security: [{ basicAuth: [] }, { oauth2: [] }]
  /reports/custom:
    post:
      summary: Run a custom report
      operationId: runCustomReport
      tags: [Reports]
      parameters:
        - { in: query, name: format, schema: { type: string, enum: [JSON, CSV, PDF, XLS, XML] } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [fields]
              properties:
                title: { type: string }
                fields:
                  type: array
                  items: { type: string }
                filters: { type: object }
      responses:
        '200':
          description: Report results
          content:
            application/json:
              schema: { type: object }
      security: [{ basicAuth: [] }, { oauth2: [] }]
  /time_off/requests:
    get:
      summary: List time off requests
      operationId: listTimeOffRequests
      tags: [Time Off]
      parameters:
        - { in: query, name: id, schema: { type: string } }
        - { in: query, name: action, schema: { type: string, enum: [view, approve] } }
        - { in: query, name: employeeId, schema: { type: string } }
        - { in: query, name: start, schema: { type: string, format: date } }
        - { in: query, name: end, schema: { type: string, format: date } }
        - { in: query, name: type, schema: { type: string } }
        - { in: query, name: status, schema: { type: string, enum: [approved, denied, superceded, requested, canceled] } }
      responses:
        '200':
          description: Time off requests
          content:
            application/json:
              schema:
                type: array
                items: { type: object }
      security: [{ basicAuth: [] }, { oauth2: [] }]
  /employees/{id}/time_off/request:
    parameters:
      - { in: path, name: id, required: true, schema: { type: string } }
    put:
      summary: Add a time off request for an employee
      operationId: addTimeOffRequest
      tags: [Time Off]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status, start, end, timeOffTypeId]
              properties:
                status: { type: string, enum: [approved, requested] }
                start: { type: string, format: date }
                end: { type: string, format: date }
                timeOffTypeId: { type: integer }
                amount: { type: number }
                notes: { type: object }
      responses:
        '201': { description: Created }
      security: [{ basicAuth: [] }, { oauth2: [] }]
  /meta/fields:
    get:
      summary: Get a list of all fields
      operationId: listFields
      tags: [Meta]
      responses:
        '200':
          description: Field metadata
          content:
            application/json:
              schema:
                type: array
                items: { type: object }
      security: [{ basicAuth: [] }, { oauth2: [] }]
  /meta/tables:
    get:
      summary: Get a list of tabular fields
      operationId: listTables
      tags: [Meta]
      responses:
        '200':
          description: Tabular field metadata
          content:
            application/json:
              schema:
                type: array
                items: { type: object }
      security: [{ basicAuth: [] }, { oauth2: [] }]
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic auth. Use the API key as the username and any non-empty string as the password.
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization code flow (for multi-customer apps).
      flows:
        authorizationCode:
          authorizationUrl: https://api.bamboohr.com/oauth/authorize.php
          tokenUrl: https://api.bamboohr.com/token.php
          scopes:
            offline_access: Issue a refresh token along with the access token
  schemas:
    Employee:
      type: object
      properties:
        id: { type: string }
        firstName: { type: string }
        lastName: { type: string }
        displayName: { type: string }
        jobTitle: { type: string }
        workEmail: { type: string }
        department: { type: string }
        location: { type: string }
        supervisor: { type: string }
        hireDate: { type: string, format: date }
        employmentHistoryStatus: { type: string }